fastapi 如何实现简单的 Bearer Token 认证中间件

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
security = HTTPBearer()
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 jw
t.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 的依赖注入范式里不破坏上下文、不绕过异常机制、不误导文档生成——这三点踩错一个，后期维护成本就翻倍。

# ai  # 是在  # 的是  # 会在  # 是因为  # 多个  # 翻倍  # 文档  # 自定义  # 写在  # app  # redis  # http  # js  # json  # go  # 路由  # 字符串  # 数据库  # 为什么  # red  # 前端  # Token  # 抛出  # 状态码  # 中间件  # fastapi 

相关栏目： <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 AI推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 SEO优化<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 技术百科<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 谷歌推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 百度推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 网络营销<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 案例网站<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 精选文章<？ｍｕｍａ echo $count; ?> 】