签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,98 @@
+# 8.6 Token 使用说明
+
+:::tip 概述
+本文档面向 API 对接方：如何获取令牌、如何携带、如何刷新、如何撤销。令牌为 JWT HS256 双令牌（access 2h + refresh 7d），唯一使用下划线命名的响应。
+:::
+
+## 获取令牌（POST /api/login，公开）
+
+```sh
+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>"}'
+```
+
+```json
+{
+  "code": 0, "ok": true, "msg": "操作成功",
+  "data": {
+    "access_token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
+    "expires_in": 7200,
+    "token_type": "Bearer"
+  }
+}
+```
+
+::: warning 命名例外
+登录/令牌接口返回 `access_token/refresh_token/expires_in/token_type`（OAuth2 惯例下划线命名）——这是全系统唯一例外，其余接口出入参一律驼峰。
+:::
+
+## 携带令牌调用业务接口
+
+```sh
+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 轮换新令牌对：
+
+```sh
+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>"}'
+```
+
+```json
+{ "data": { "access_token": "…", "refresh_token": "…", "expires_in": 7200, "token_type": "Bearer" } }
+```
+
+刷新语义：
+
+```text
+* 旧 refresh 入黑名单（轮换）——旧 refresh_token 立即作废，必须存新值
+* 旧 access 自然过期（不主动拉黑）
+* 返回同登录格式四字段
+* 兼容密码模式：grant_type=password 或无 refresh_token → 复用登录逻辑
+```
+
+## 撤销与校验
+
+```text
+GET  /api/logout                     登出（当前 access jti 拉黑）
+DELETE /api/oauth2/remove/:token     撤销指定令牌（登录可用；解析 jti 入黑名单）
+GET  /api/oauth2/check/token        校验令牌有效性（JWT 中间件通过即有效）
+```
+
+## 对接方实现要点
+
+```text
+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 双令牌拉黑）