跳到主要内容

BasicIdentity 开发指南

FreeKit.BasicIdentity 是 Identity 的轻量级认证子模块，面向"只需要登录 + 用户资料，不需要完整 RBAC/租户/组织架构"的场景。它复用了 Identity 的底层能力（AddFreeKitCore、FreeSql、Token 机制、邮件发送），但用一套简化用户模型替代了完整的 IdentityUser + 角色/权限体系。

配套概览页见 BasicIdentity 基础认证。

1. 与完整 Identity 的差异​

维度完整 IdentityBasicIdentity
用户实体IdentityUser（ASP.NET Identity，含审计/多租户/声明等）User（sys_user 表，仅 UserName/NickName/Email/Phone/Password(Salt)/Role/Status 等精简字段）
角色IdentityRole 表 + 多对多 + 数据范围仅一个字符串字段 Role（Admin / User，见 RoleConst）
权限完整权限树 + IPermissionManagerBasicIdentityPermissionStore（只校验 Token 有效性，不维护权限树）
租户 / 组织 / 员工支持不支持
控制器20+ 个仅 Account / Profile / User（测试用）
注册入口BasicIdentityModuleStartupBasicIdentityModuleStartup（IModuleStartup，框架自动发现）

BasicIdentityModuleStartup.Configure(...) 仅 SyncStructure(typeof(User), typeof(UserToken)) 两张表，因此部署体量与依赖都更小。

2. 关键服务​

  • IUserService（FreeKit.BasicIdentity.Application.Auth.Contracts）— 按 Id 取用户、按 Token/当前用户取 CurrentUserDto / BasicCurrentUser。
  • IProfileService — 资料读写。
  • ITokenManager（FreeKit.BasicIdentity.Application.Auth.Login，IDomainService）— 登录签发 Token 的领域服务。
  • 命令层（MediatR）：RegisterCommand / LoginCommand / LogoutCommand / RefreshTokenCommand / UpdateAvatarCommand，由 AccountController / ProfileController 派发。

用户写操作的入口是注册命令与资料命令；没有类似完整 Identity 的"用户 CRUD 控制器"。UserController 仅含 test-role-admin / test-role-user 两个鉴权自测端点。

3. HTTP API​

所有路由前缀均为 /api/identity/...（注意：不是 /api/basic/...）。

Account — /api/identity/account​

方法路由说明
POST/register注册（RegisterCommand：用户名 + 密码 + 邮箱）
POST/login登录，返回 UserAccessToken（LoginCommand）
POST/logout注销（吊销当前 Token，AllowAnonymous）
GET/refresh-token?refreshToken=用 RefreshToken 换新 Token（AllowAnonymous）

Profile — /api/identity/profile​

方法路由说明
POST/verify校验是否已登录（返回当前用户 Id）
POST/userinfo · GET/information
GET/current-user-by-token?accessToken=按 Token 取当前用户（AllowAnonymous）
PUT/avatar设置自己头像（UpdateAvatarCommand，带 avatarKey）

User — /api/identity/user（自测）​

方法路由说明
GET/test-role-admin需 Admin 角色（[Authorize(Roles=Admin)]）
GET/test-role-user需 User 角色

4. 配置​

BasicIdentity 复用与完整 Identity 相同的 Token 配置：

{
  "Authentication": {
    "ExpiresTime": 86400,
    "RefreshExpiresIn": 2592000
  },
  "ConnectionStrings": {
    "DefaultDB": "0",
    "LogConnectionStrings": "..."
  }
}

密码以 Salt + Password 形式存储在 User 表；角色为字符串常量（RoleConst.Admin / RoleConst.User），鉴权时通过 [Authorize(Roles=...)] 校验。

5. 接入与示例​

// 框架自动发现并启动 BasicIdentityModuleStartup（IModuleStartup）
// 宿主启动后路由即生效，无需手动 AddBasicIdentity()
# 注册
curl -X POST https://localhost:7002/kit_api/api/identity/account/register \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"Password123!","email":"test@example.com"}'

# 登录
curl -X POST https://localhost:7002/kit_api/api/identity/account/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"Password123!"}'

# 取当前用户资料
curl https://localhost:7002/kit_api/api/identity/profile/information \
  -H "Authorization: Bearer <accessToken>"

相关文档​