令牌自动刷新的核心逻辑是：access_token过期后中间件捕获401，用有效的refresh_token换取新token并重放请求；需避免并发刷新、保证安全存储与及时作废。
令牌自动刷新的核心逻辑
用户登录后获得的访问令牌（access_token）通常有较短有效期（如15分钟），而刷新令牌（refresh_token）有效期更长（如7天）。自动刷新不是“后台偷偷换token”，而是当请求携带的 access_token 过期时，中间件捕获 401 错误，用 refresh_token 向认证服务换新 access_token，并重放原始请求。
关键点：
- 不在每次请求都刷新，只在 access_token 确认过期且 refresh_token 有效时才触发
- 刷新过程对前端透明，前端仍按原方式发请求，中间件负责兜底重试
- 避免并发刷新：同一用户多个请求同时过期时，只允许一个线程去刷新，其余等待结果
FastAPI 中间件实现校验与刷新
用 FastAPI 的 BaseHTTPMiddleware 拦截请求，在请求头中提取 Authorization Bearer token，解析并校验 JWT：
- 用 PyJWT 验签 + 检查 exp 字段，捕获
ExpiredSignatureError - 若过期，从请求上下文或 Redis 中取出该用户的 refresh_token（需提前绑定 user_id 和 refresh_token）
- 调用内部 /auth/refresh 接口（或直接解密 refresh_token，若它也是 JWT 且服务端可验签）
- 成功获取新 access_token 后，替换响应头中的 Authorization，或返回 401 + 新 token 供前端更新本地存储
注意：不要在中间件里直接修改 request.state —— 它是只读的；刷新结果建议通过 Response.headers 或自定义 JSON 响应体透出。
避免重复刷新与状态同步
多个请求几乎同时到达，都发现 token 过期，会引发多次刷新请求，浪费资源甚至导致 refresh_token 被单次使用后失效（若策略为“用完即焚”）：
立即学习“Python免费学习笔记（深入）”；
- 用内存字典或 Redis 的 SETNX + 过期时间模拟锁：key 为 user_id，value 为 promise 或 task id
- 首个请求加锁、发起刷新；后续请求检查锁存在则等待（可用 asyncio.wait_for + 共享 future）
- 刷新完成后主动广播新 token，或让等待方轮询一次结果（推荐前者，更实时）
- 前端也需配合：收到 401 且响应含 new_access_token 时，自动更新 localStorage 并重试原请求
安全与生产注意事项
自动刷新不是银弹，必须搭配合理安全策略：
- refresh_token 必须 HttpOnly + Secure + SameSite=Strict 存储在 Cookie 中，禁止 JS 访问
- 每次使用 refresh_token 后，立即作废旧 token（服务端记录黑名单或滚动更新）
- 限制 refresh_token 使用频次（如 1 小时内最多刷新 3 次），防暴力试探
- access_token 尽量精简载荷（不存敏感字段），校验时只依赖签名校验和标准字段（exp, iat, iss）
- 日志中脱敏处理 token 字符串，避免泄露到错误日志
基本上就这些。不复杂但容易忽略细节，尤其是锁机制和前后端协同时机。写好中间件后，真正的业务路由完全不用感知 token 刷新过程。
