FastAPI 中应使用模块级 HTTPBearer 实例提取 Bearer Token，再通过 Depends 注入自定义验证函数校验有效性；避免手动解析或放入中间件，以确保异常自动转换、OpenAPI 文档正确生成及依赖注入可用。
FastAPI 中如何用 HTTPBearer 提取 Bearer Token
FastAPI 官方推荐用 HTTPBearer（来自 fastapi.security）提取请求头中的 Authorization: Bearer xxx，它会自动校验格式、抛出 403 或 401。别自己用 request.headers.get("Authorization") 手动解析——容易漏掉空格、大小写、前缀缺失等边界情况。
常见错误现象：credentials: None 或 Invalid authentication credentials 报错但没说明原因，往往是因为前端传了 authorization: bearer xxx（小写 bearer）或少了空格。
-
HTTPBearer默认要求Bearer全大写、后跟一个空格，不接受bearer或BEARER - 若需兼容大小写，得自定义
scheme_name并重写__call__，但一般不建议 - 它只负责提取 token 字符串，不做验证；验证逻辑必须单独实现
如何写一个可复用的 token 验证依赖
把 token 解析和验证拆成两步：先用 HTTPBearer 提取，再用自定义函数校验有效性（比如查 Redis、验 JWT 签名）。直接在路由里写验证逻辑会导致重复和耦合。
实操建议：定义一个 Depends 函数，接收 credentials: HTTPAuthorizationCredentials，返回用户标识（如 user_id: str）或抛出 HTTPException。
- 验证失败时，抛
HTTPException(status_code=401, detail="Invalid or expired token")，FastAPI 自动转为标准响应 - 不要返回
None或静默失败，否则后续逻辑可能 panic - 若 token 是 JWT，用
PyJWT的jwt.decode(..., options={"verify_signature": True})，避免跳过签名检查
from fastapi import Depends, HTTPException from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials from jose import jwt <p>security = HTTPBearer()</p><p>async def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)): try: payload = jwt.decode(credentials.credentials, "SECRET_KEY", algorithms=["HS256"]) return payload["sub"] # 假设 sub 是 user_id except jwt.ExpiredSignatureError: raise HTTPException(401, "Token expired") except jwt.JWTError: raise HTTPException(401, "Invalid token")
为什么不能把认证逻辑写在中间件里
FastAPI 的中间件（@app.middleware("http")）运行在路由分发之前，此时你拿不到路径、方法、依赖注入上下文，也无法自然地返回 401 响应（只能靠 Response 构造，绕过 FastAPI 的异常处理机制）。
更关键的是：中间件无法参与依赖注入生命周期，意味着你没法用 Depends 注入数据库连接、缓存客户端等资源——而 token 验证几乎总要查 DB 或 Redis。
- 中间件适合做日志、CORS、请求体限流等与业务逻辑无关的横切操作
- 认证是业务强相关行为，必须走依赖注入链，才能享受自动异常转换、OpenAPI 文档标注等特性
- 强行塞进中间件会导致 OpenAPI 文档里不显示
401状态码，前端 SDK 生成失真
如何让 OpenAPI 文档正确显示 Bearer Auth
只要用了 Depends(security) 或基于它的依赖（如上面的 verify_token），FastAPI 就会在 /docs 页面自动渲染 “Authorize” 按钮，并生成带 SecurityScheme 的 JSON Schema。
但容易被忽略的一点是：如果你把 HTTPBearer() 实例化写在函数内部（比如每次调用都 HTTPBearer()），文档里会出现多个重复的 auth 方案。必须定义为模块级变量：
- ✅ 正确：
security = HTTPBearer()在文件顶部，然后Depends(security) - ❌ 错误：
Depends(HTTPBearer())直接传调用结果，会导致文档混乱 - 如果需要不同 token 类型（如 admin vs user），才考虑多个命名实例，如
admin_security = HTTPBearer(scheme_name="AdminBearer")
token 验证本身不难，难的是在 FastAPI 的依赖注入范式里不破坏上下文、不绕过异常机制、不误导文档生成——这三点踩错一个，后期维护成本就翻倍。
