Python WebAPI如何实现令牌自动刷新与校验中间件【教程】

令牌自动刷新的核心逻辑是：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 被单次使用后失效（若策略为“用完即焚”）：

文心智能体平台

百度推出的基于文心大模型的Agent智能体平台，已上架2000+AI智能体

393

查看详情

立即学习“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 刷新过程。

以上就是Python WebAPI如何实现令牌自动刷新与校验中间件【教程】的详细内容，更多请关注php中文网其它相关文章！