OAuth2PasswordBearer单独无法实现OAuth2认证，因其仅提取Bearer Token而不验证；必须配合/token端点签发JWT和get_current_user依赖校验token，且payload须含sub、exp、iat字段。
OAuth2PasswordBearer 是 FastAPI 中处理 OAuth2 授权流程的起点，但它本身不实现任何逻辑——它只负责从请求头提取 Authorization: Bearer <token>，并抛出 401 错误。真正构成“符合 OAuth2 规范”的授权流程，必须补全两个核心环节：令牌颁发（/token） 和 令牌校验（依赖注入）。
为什么 OAuth2PasswordBearer 单独用不了？
它只是一个“取 token 的工具”，不是认证器。常见错误是只配了 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")，然后在路由里 Depends(oauth2_scheme)，结果所有请求都返回 401，连登录入口都没有。
OAuth2 密码流要求明确区分两个端点：
-
POST /auth/token：接收username和password，验证后签发 JWT -
GET /protected：用Depends(get_current_user)提取并校验 token，返回当前用户对象
缺一不可。否则就只是“假装支持 OAuth2”。
立即学习“Python免费学习笔记（深入）”；
create_access_token() 必须包含哪些关键字段？
JWT Payload 不是随便塞数据。OAuth2 要求至少包含：sub（subject，即用户唯一标识）、exp（过期时间）、iat（签发时间）。FastAPI 官方示例常漏掉 iat，但它是防重放攻击的基础。
示例 payload：
{
"sub": "user123",
"exp": 1719152000,
"iat": 1719148400,
"scopes": ["read:items"]
}注意：scopes 字段用于后续权限控制，不能硬编码，应从数据库或用户角色动态生成；exp 建议用 datetime.utcnow() + timedelta(minutes=30) 计算，别用固定秒数。
第三方登录（如 GitHub）和密码流本质不同
很多人混淆 OAuth2PasswordBearer 和第三方 OAuth2 登录。前者是“自有账号密码登录”，后者是“跳转到 GitHub 登录页 → 拿授权码 → 换 token → 拉用户信息”。两者共用 OAuth2 协议，但流程、依赖库、错误处理完全不同。
GitHub 登录必须用 oauthlib 或 httpx_oauth 手动实现授权码交换，不能靠 OAuth2PasswordBearer。常见坑：
- 回调地址（
redirect_uri）必须和 GitHub 后台注册的一致，包括末尾斜杠 - 换 token 时传错参数名（GitHub 要
client_id、client_secret、code、redirect_uri，少一个就 401） - 拿到 GitHub token 后，必须再发一次
GET https://api.github.com/user才能拿到用户名，不能直接当用户 ID 用
Token 吊销和刷新机制容易被忽略
标准 OAuth2 要求支持 refresh_token，但 JWT 默认无状态，无法单点吊销。真实项目中，要么：
- 加 Redis 缓存黑名单（
blacklist:<jti>），每次校验前查一次 - 把 refresh token 存数据库，绑定 client_id + user_id + exp，每次换新 token 时作废旧的
- 干脆不用 refresh token，让前端在 30 分钟后强制重新登录（适合内部系统）
不处理吊销，等于把 “永久有效” 的 token 当短期 token 用——这是生产环境最常被审计挑出的问题。
