8.6 Token 使用说明

概述

本文档面向 API 对接方：如何获取令牌、如何携带、如何刷新、如何撤销。令牌为 JWT HS256 双令牌（access 2h + refresh 7d），唯一使用下划线命名的响应。

获取令牌（POST /api/login，公开）

curl -X POST http://127.0.0.1:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456","code":"618618","key":"<captcha-key>"}'

{
  "code": 0, "ok": true, "msg": "操作成功",
  "data": {
    "access_token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

命名例外

登录/令牌接口返回 access_token/refresh_token/expires_in/token_type（OAuth2 惯例下划线命名）——这是全系统唯一例外，其余接口出入参一律驼峰。

携带令牌调用业务接口

curl http://127.0.0.1:8000/api/user/page?pageNo=1&pageSize=10 \
  -H "Authorization: Bearer <access_token>"

兼容细节：Bearer 前缀大小写不敏感、可无前缀直接传 token；个别场景支持查询参数 ?token=（URL 直传）。

刷新令牌（POST /api/oauth2/token，公开）

access 过期（收到 code=401）时用 refresh_token 轮换新令牌对：

curl -X POST http://127.0.0.1:8000/api/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"<refresh_token>"}'

{ "data": { "access_token": "…", "refresh_token": "…", "expires_in": 7200, "token_type": "Bearer" } }

刷新语义：

* 旧 refresh 入黑名单（轮换）——旧 refresh_token 立即作废，必须存新值
* 旧 access 自然过期（不主动拉黑）
* 返回同登录格式四字段
* 兼容密码模式：grant_type=password 或无 refresh_token → 复用登录逻辑

撤销与校验

GET  /api/logout                     登出（当前 access jti 拉黑）
DELETE /api/oauth2/remove/:token     撤销指定令牌（登录可用；解析 jti 入黑名单）
GET  /api/oauth2/check/token        校验令牌有效性（JWT 中间件通过即有效）

对接方实现要点

1. 存储：access 与 refresh 分开存（内存/localStorage）；refresh 泄露=账号风险
2. 请求：全部业务请求带 Authorization: Bearer <access>
3. 401 处理：单飞刷新（并发 401 只触发一次 refresh，其余等结果）；
   refresh 失败（1008/401）→ 清令牌 → 跳登录
4. 刷新成功：立即用新令牌对覆盖旧值（旧 refresh 已作废）
5. 时钟偏移：以 expires_in 倒计时提前刷新（如过期前 60s），减少 401
6. 登出：调 /api/logout 后清本地——不调的话令牌有效期内仍可用

令牌状态速查

状态	表现	处理
有效	业务正常	—
access 过期	code=401	refresh 轮换
refresh 过期/已轮换	code=1 或 1008	重新登录
已拉黑（登出/强退）	code=401	重新登录（强退的 refresh 也拉黑，无法复活）
算法/签名无效	code=401	检查是否跨环境混用 jwt.secret

安全建议

• HTTPS 传输（令牌明文等价于会话）
• refresh_token 泄露面最小化（不入 URL、不入日志——后端已脱敏）
• 客户端不持久化 access（内存优先）；persist refresh 的场景加密存储
• 多端登录场景用在线用户模块管理（forceLogout 双令牌拉黑）