跳到主要内容

BasicIdentity 模块文档

1. 模块概述​

BasicIdentity 是一个轻量级的身份认证模块，提供基本的用户管理和认证功能，适用于小型应用或作为大型应用的基础身份服务。

1.1 核心功能​

  • 用户管理：用户注册、登录、个人资料管理
  • 认证功能：JWT令牌认证、刷新令牌
  • 角色管理：基础角色分配（Admin、User）
  • 个人资料：头像设置、个人信息管理

1.2 技术架构​

  • 基于 ASP.NET Core 构建
  • 使用 FreeSql 作为 ORM 框架
  • 集成 JWT 认证
  • 采用 MediatR 实现命令和查询分离

2. 核心功能模块​

2.1 认证模块​

2.1.1 登录功能​

  • API：POST /api/account/login
  • 参数：用户名/邮箱、密码
  • 返回：访问令牌、刷新令牌、用户信息

2.1.2 注册功能​

  • API：POST /api/account/register
  • 参数：用户名、密码、邮箱、手机号
  • 返回：用户信息

2.1.3 刷新令牌​

  • API：POST /api/account/refresh-token
  • 参数：刷新令牌
  • 返回：新的访问令牌、新的刷新令牌

2.1.4 登出功能​

  • API：POST /api/account/logout
  • 参数：无
  • 返回：成功状态

2.2 个人资料模块​

2.2.1 获取用户信息​

  • API：GET /api/profile
  • 参数：无
  • 返回：用户详细信息

2.2.2 设置头像​

  • API：POST /api/profile/avatar
  • 参数：头像文件
  • 返回：头像URL

2.2.3 验证登录状态​

  • API：GET /api/profile/verify
  • 参数：无
  • 返回：登录状态、用户信息

4. 配置与部署​

4.1 模块注册​

List<Type> typeAssemblies = new List<Type>()
{
    typeof(Program),
    typeof(IApplicationService),
    typeof(FreeKitModule),
    typeof(BasicIdentityModuleStartup),
};

containerBuilder.RegisterModule(new FreeKitModule(typeAssemblies.ToArray(), null));
containerBuilder.RegisterModule(new UnitOfWorkModule(typeAssemblies.ToArray(), null));

4.2 服务依赖​

services.AddModule<BasicIdentityModuleStartup>("module-basic-identity", c);

4.3 CAP配置​

var assemblies = new List<Assembly>
{
    typeof(BasicIdentityModuleStartup).Assembly,
    typeof(CmsKitModuleStartup).Assembly,
};

services.AddKitCap(c) // 分布式事务一致性CAP
.AddSubscriberAssembly(assemblies.ToArray());

4.4 Swagger配置​

var projectNames = new List<string>()
{
    "FreeKit.CmsKit",
    "FreeKit.BasicIdentity"
};
//注入业务服务
services.AddSwagger(c, projectNames);

5. 使用示例​

5.1 登录示例​

// 登录请求
var loginCommand = new LoginCommand("admin", "Password123!");
var token = await mediator.Send(loginCommand);

// 使用令牌
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);

5.2 注册示例​

// 注册请求
var registerCommand = new RegisterCommand
{
    UserName = "user1",
    Password = "Password123!",
    Email = "user1@example.com",
    PhoneNumber = "13800138000"
};
var user = await mediator.Send(registerCommand);

5.3 刷新令牌示例​

// 刷新令牌请求
var refreshTokenCommand = new RefreshTokenCommand("refresh_token_value");
var newToken = await mediator.Send(refreshTokenCommand);

6. 最佳实践​

6.1 安全最佳实践​

  • 使用HTTPS保护API通信
  • 实施密码复杂度要求
  • 限制登录尝试次数
  • 定期轮换令牌密钥

6.2 性能最佳实践​

  • 使用缓存减少数据库查询
  • 合理设置令牌过期时间
  • 批量操作减少API调用

7. 常见问题与解决方案​

7.1 登录失败​

  • 检查用户名和密码是否正确
  • 检查用户状态是否激活
  • 检查账号是否被冻结

7.2 令牌过期​

  • 使用刷新令牌获取新的访问令牌
  • 检查令牌过期时间配置
  • 实现自动刷新令牌机制

7.3 注册失败​

  • 检查用户名是否已存在
  • 检查邮箱格式是否正确
  • 检查密码复杂度是否满足要求

8. 未来规划​

  • 支持更多认证方式
  • 增强用户管理功能
  • 集成第三方登录
  • 提供更多的安全特性