JWT认证在FastAPI中需手动实现签名验证、过期检查等逻辑，OAuth2PasswordBearer仅提取Bearer Token；须用python-jose解析并校验exp、aud、iss等字段，生产环境密钥应从环境变量加载且满足HS256长度要求。
JWT 认证在 FastAPI 中的核心组件是 OAuth2PasswordBearer
FastAPI 本身不内置 JWT 解析逻辑，而是依赖 OAuth2PasswordBearer（一个用于提取 Bearer Token 的依赖项）配合手动验证。它只负责从 Authorization: Bearer <token></token> 头里取值，不校验签名、过期或 payload 结构——这些必须自己用 PyJWT 或 python-jose 实现。
常见错误是以为 OAuth2PasswordBearer 能自动验签或刷新 token，其实它连 decode 都不做。你得在依赖函数里显式调用 jwt.decode() 并捕获 JWTError、ExpiredSignatureError 等异常。
-
OAuth2PasswordBearer初始化时传入的tokenUrl只影响 OpenAPI 文档的“Authorize”按钮跳转地址，和实际认证流程无关 - 务必设置
algorithm和key—— 用硬编码密钥仅限开发；生产环境应从环境变量读取，且密钥长度需满足 HS256 要求（至少 32 字节） - 别漏掉
audience和issuer校验（如果 token 是由外部 IdP 签发），否则可能接受伪造 audience 的 token
如何安全生成并返回 JWT token
登录接口（如 /token）收到用户名密码后，先校验凭据（比如查数据库、比对哈希），再用 jwt.encode() 生成 token。关键不是“怎么 encode”，而是“该塞什么进 payload”。
- 必须包含
exp（建议用datetime.utcnow() + timedelta(minutes=30)），否则 token 永不过期 - 推荐加入
sub（subject，通常是用户 ID 或 username），后续依赖中可直接从中提取用户标识 - 避免放入敏感信息（如密码、手机号），JWT 是 Base64 编码，非加密——用
HS256只防篡改，不防泄露 - 返回时用
JSONResponse或 Pydantic 模型，字段名保持为access_token和token_type（值固定为"bearer"），以便前端和 Swagger UI 正确识别
如何在路由中使用 Depends 提取当前用户
定义一个依赖函数（比如叫 get_current_user），把它作为参数传给 Depends()，FastAPI 就会在每次请求时自动执行它，并把返回值注入到路由函数参数中。
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
这个函数内部要：解析 token → 验证签名和时效 → 查询用户数据 → 返回用户对象（或抛出 HTTPException(status_code=401)）。注意几个易错点：
- 别在依赖里直接返回
dict，最好用 Pydantic 模型封装用户字段（如id,username,scopes），方便类型提示和后续扩展 - 如果需要权限控制（如 admin-only），可在同一依赖中检查
payload.get("scopes")，而不是另写一个依赖 - 不要在多个路由里重复写 token 解析逻辑——依赖就是干这个的，复用它
- 异常必须是
HTTPException，不能是裸raise ValueError，否则 FastAPI 不会转成 401 响应
为什么 python-jose 比 PyJWT 更适合 FastAPI
虽然两者都能 decode/sign JWT，但 python-jose 是 FastAPI 官方文档指定库，且与 OAuth2PasswordBearer 的类型提示、错误类（如 JWSSignatureError）深度集成。用 PyJWT 会导致部分错误类型不匹配，比如 ExpiredSignatureError 在 python-jose 里对应的是 ExpiredSignatureError，但名字和继承链不同，统一捕获容易漏。
另外，python-jose 对 RS256 支持更稳定（如果你后续要对接 Keycloak 或 Auth0），而 PyJWT 在某些版本中对 PEM 密钥加载行为不一致。
- 安装时明确指定：
pip install python-jose[cryptography]，否则cryptography后端可能缺失 - 解码时用
jwt.decode(token, key, algorithms=["HS256"])，algorithms必须是列表，不能是字符串，否则报TypeError -
jwt.encode()的expires_delta参数不存在——它只接受exp时间戳，别被某些过时博客误导
最常被忽略的是 clock skew：服务器时间不准会导致 token 频繁报 Token expired，即使刚生成。上线前务必用 ntpdate 或 systemd-timesyncd 同步时间，或者在 jwt.decode() 里加 leeway=10（允许 10 秒偏差）。
