OAuth2PasswordBearer 实例化必须传入与登录接口完全一致的 tokenUrl（如"/api/v1/token"），且应作为模块级常量声明；密码流需手动验证用户、用python-jose签发JWT，密钥须从环境变量读取。
OAuth2PasswordBearer 实例化时必须传入 tokenUrl
FastAPI 的 OAuth2PasswordBearer 不是认证逻辑本身，只是一个依赖项工具，用于从请求头中提取 Authorization: Bearer <token>。它必须明确知道令牌的获取地址（tokenUrl），否则后续 Swagger UI 的“Authorize”按钮无法自动填充表单，调试时会卡在 401 且无提示。
常见错误是写成 OAuth2PasswordBearer(tokenUrl="token") 却没定义对应路由；或路径写成 /auth/token，但实际接口注册在 /api/v1/login —— 这会导致文档里点击 Authorize 后跳转失败，返回 404。
-
tokenUrl必须与你后续实现的登录接口路径完全一致（包括前缀、大小写、斜杠） - 建议统一用绝对路径，如
tokenUrl="/api/v1/token"，避免前端代理或部署子路径时出错 - 如果使用 APIRouter 前缀，
tokenUrl应与最终暴露的 URL 匹配，而非 router 的 prefix
密码流登录接口必须手动验证用户并调用 create_access_token
FastAPI 不提供内置的用户校验或 JWT 签发函数。OAuth2PasswordRequestForm 只负责解析 username 和 password 字段（来自表单编码，不是 JSON），其余全部需自行实现：查库、比对密码、生成 token。
JWT 签发推荐用 python-jose（FastAPI 官方示例所用），而非 PyJWT，因前者默认启用更严格的签名算法和过期检查。
立即学习“Python免费学习笔记（深入）”；
- 务必用
bcrypt或passlib验证密码，禁止明文比对 -
create_access_token函数应接收data: dict（如{"sub": "user123"}）、expires_delta: timedelta，并使用jwt.encode(..., algorithm="HS256") - 密钥（
SECRET_KEY）必须存为环境变量，绝不可硬编码；长度建议 ≥32 字节（如用secrets.token_urlsafe(32)生成）
示例片段：
from jose import jwt
from datetime import timedelta
<p>SECRET_KEY = "your-super-secret-key-here"
ALGORITHM = "HS256"</p><p>def create_access_token(data: dict, expires_delta: timedelta):
to_encode = data.copy()
expire = datetime.utcnow() + expires_delta
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
依赖项中嵌套调用 OAuth2PasswordBearer 会破坏依赖注入链
不要在自定义依赖函数内部再实例化 OAuth2PasswordBearer。例如下面这种写法是错的：
def get_current_user(token: str = Depends(OAuth2PasswordBearer(tokenUrl="/token"))): # ❌ 错误：重复实例化
...
正确做法是：全局只定义一次 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/token")，然后所有需要鉴权的地方都直接 Depends(oauth2_scheme)。否则 FastAPI 无法统一管理依赖生命周期，Swagger 文档会丢失认证配置，且每次调用都新建对象，影响性能。
- 把
OAuth2PasswordBearer实例作为模块级常量声明，而不是函数内局部变量 - 若需多套认证方案（如 admin/user 分开 tokenUrl），才分别定义多个 scheme，但每个仍应是常量
- 依赖项函数（如
get_current_user）只接收已提取的token: str，不负责提取
JWT 解析失败时要区分 InvalidTokenError 和 ExpiredSignatureError
用 jwt.decode() 验证 token 时，不同异常代表不同问题：ExpiredSignatureError 是过期，InvalidTokenError（或其子类如 JWTError）可能是签名无效、格式错误、issuer 不匹配等。统一捕获 JWTError 并返回 401 是合理的，但日志中应保留具体类型，方便排查。
- 不要忽略
credentials_exception = HTTPException(status_code=401, ...)的headers={"WWW-Authenticate": "Bearer"}，这是标准响应头，客户端（如 Axios）靠它识别认证失败 - 避免在 decode 时设置
options={"verify_exp": False}，这等于关闭过期检查，存在安全风险 - 若使用
audience或issuer，确保签发和验证时参数严格一致，字符串比较区分大小写
JWT 签发和校验的密钥、算法、有效期、payload 结构这些点，一旦上线就很难变更，尤其当 token 已下发到客户端。初始化时多花两分钟核对 SECRET_KEY 来源和 tokenUrl 路径，能省掉后续半天的日志排查。
