2.2 KiB
2.2 KiB
8.7 Token 使用说明
:::tip 概述
客户端持有 access_token + refresh_token 双令牌：请求携带 access，过期后用 refresh 兑换新令牌。401 是唯一的"令牌失效"信号。本页字段以 internal/model/dto/auth.go 为准。
:::
获取
POST /api/login（公开，参数支持 query/body 混合提交）
{
"username": "...",
"password": "...",
"key": "<captcha 接口返回的 key>",
"code": "<验证码>",
"tenantCode": "" // 留空按用户名全局定位
}
响应 data（LoginRes）：
{
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"expires_in": 7200,
"token_type": "Bearer"
}
携带
Authorization: Bearer eyJ...
前端请求拦截器自动附加；业务代码不手工处理。
刷新
POST /api/oauth2/token（公开）
grant_type=refresh_token 模式：
{ "grant_type": "refresh_token", "refresh_token": "<refresh_token>" }
grant_type=password 模式（兑换）：
{ "grant_type": "password", "username": "...", "password": "...", "code": "...", "key": "..." }
响应 RefreshRes 结构与登录一致（access_token / refresh_token / expires_in / token_type）。旧 refresh 拉黑（防重放）。
校验
GET /api/oauth2/check/token（携带 Authorization）
响应（CheckTokenRes）：{ "valid": true, "userId": 1 }
valid=false 时 userId 按 0 返回。
失效场景
| 场景 | 表现 |
|---|---|
| access 过期 | 401 → 前端刷新或跳登录 |
| 登出 | 双令牌入黑名单，立即失效 |
| 强制下线 | 指定会话双令牌拉黑 |
| 撤销 | DELETE /api/oauth2/remove/:token（管理员） |
黑名单 TTL = 令牌剩余有效期，到期自然失效，无需清理。
客户端处理建议
收到 401 →
有 refresh_token 且未尝试过 → 调 /api/oauth2/token 刷新 → 重放原请求（刷新只尝试一次，防死循环）
否则 → 清本地令牌 → 跳登录页
调试
Swagger 调试：先登录拿 access_token，在文档页填入 Authorization 后调用受保护接口。