登录认证

登录认证负责确认用户身份、签发访问令牌，并把用户的角色、部门和数据权限带入后续请求链路。

认证入口

• 获取图形验证码：GET /api/v1/auth/captcha
• 账号密码登录：POST /api/v1/auth/login
• 刷新令牌：POST /api/v1/auth/refresh-token
• 退出登录：DELETE /api/v1/auth/logout

获取验证码

GET /api/v1/auth/captcha

响应示例：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "captchaId": "9f0b2c...",
    "captchaBase64": "data:image/png;base64,..."
  }
}

登录接口

POST /api/v1/auth/login
Content-Type: application/json

请求参数：

{
  "username": "admin",
  "password": "123456",
  "captchaId": "9f0b2c...",
  "captchaCode": "1234"
}

响应示例：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "tokenType": "Bearer",
    "accessToken": "...",
    "refreshToken": "...",
    "expiresIn": 7200
  }
}

accessToken 用于访问后续受保护接口，refreshToken 用于刷新访问令牌。

刷新令牌

POST /api/v1/auth/refresh-token
Content-Type: application/x-www-form-urlencoded

请求参数：

refreshToken=<refreshToken>

响应结构与登录接口一致。

退出登录

DELETE /api/v1/auth/logout

退出登录会使当前访问令牌失效。JWT 模式下写入黑名单，Redis-Token 模式下删除会话。

会话模式

youlai-gin 通过 security.sessionType 选择会话模式：

security:
  sessionType: jwt # jwt | redis-token

模式	说明
jwt	令牌自带用户声明，配合 tokenVersion 和黑名单处理失效
redis-token	access/refresh token 存入 Redis，便于会话查询、刷新和踢下线

推荐生产环境使用 redis-token 或启用 JWT 安全版本号，避免纯无状态 JWT 无法主动失效的问题。

JWT 生成

JWT 由 TokenManager.GenerateToken() 统一生成，核心声明来自 UserDetails：

type UserDetails struct {
    UserID     int64
    Username   string
    DeptID     types.BigInt
    DataScopes []permModel.RoleDataScope
    Roles      []string
}

JWT Claims 中包含：

type CustomClaims struct {
    UserID         int64
    Username       string
    DeptID         types.BigInt
    DataScopes     []permModel.RoleDataScope
    Roles          []string
    IsRefreshToken bool
    TokenVersion   int
    jwt.RegisteredClaims
}

关键点：

• userId、username 用于识别当前用户。
• deptId、dataScopes 用于数据权限过滤。
• roles 用于角色判断和权限扩展。
• isRefreshToken 区分访问令牌和刷新令牌。
• tokenVersion 用于让历史 Token 主动失效。
• RegisteredClaims.ID 是 token 唯一标识，可用于黑名单。

扩展字段

扩展 JWT 字段时遵循一个原则：只放请求链路高频使用、体积可控、变更频率低的信息。

适合放入 JWT：

• tenantId：多租户场景。
• deptId：数据权限过滤。
• roles：角色判断。
• tokenVersion：会话失效控制。

不适合放入 JWT：

• 手机号、邮箱等敏感信息。
• 大量按钮权限列表。
• 经常变化的用户资料。
• 临时状态和一次性验证码。

扩展步骤：

1. 在 UserDetails 中增加字段。
2. 在 CustomClaims 中增加同名声明。
3. 生成 Token 时写入字段。
4. 解析 Token 时还原到 UserDetails。
5. 调整认证中间件和依赖该字段的业务逻辑。

会话失效

会话模式	失效方式
jwt	退出登录时将 token id 写入黑名单；禁用用户或重置密码时递增安全版本号
redis-token	删除 Redis 中的 access/refresh 会话记录

JWT 安全版本号校验逻辑：

claims.tokenVersion < redis.tokenVersion => Token 失效