权限校验必须放在Depends中，不可写在路由函数内；需用异步依赖函数封装JWT解析、角色查询、权限树比对及资源上下文校验，避免硬编码字符串权限、同步数据库操作和第三方库黑盒依赖。
权限校验必须放在 Depends 里，不能写在路由函数内部
很多人把权限判断逻辑直接塞进 get_user 或 update_profile 这类函数里，看似能跑通，但会绕过 FastAPI 的依赖注入生命周期，导致 OpenAPI 文档不生成安全要求、中间件无法统一拦截、测试时难以 mock 权限状态。
正确做法是把整个验证流程封装成一个异步依赖函数，用 Depends 注入到路径操作函数参数中。FastAPI 会在调用业务逻辑前强制执行它，并自动处理异常（如返回 401/403）。
- JWT 解析失败 → 抛
HTTPException(status_code=401)，由OAuth2PasswordBearer自动触发认证头提示 - 角色不匹配 → 抛
HTTPException(status_code=403)，避免业务逻辑执行任何副作用 - 数据库查询必须加
await，同步查询会阻塞事件循环，尤其在高并发下暴露性能瓶颈
require_permission("admin:delete_user") 这种写法容易漏掉权限继承逻辑
硬编码字符串权限码看似简单，但实际项目中角色之间存在继承关系：比如 "admin" 应该自动拥有 "user:read"、"user:update" 等所有子权限。如果只做字符串精确匹配，就会导致管理员被拒绝访问基础接口。
更健壮的做法是预定义权限树或使用集合运算：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 从数据库查出用户所有角色 → 获取每个角色对应的权限列表 → 合并去重为
set - 检查
"user:delete"是否在该集合中，而不是用==或in做模糊匹配 - 避免把权限存成逗号分隔字符串（如
"user:read,user:update"），这种格式无法高效查询、不支持索引、易出解析错误
角色校验不能只看数据库字段，必须结合请求上下文动态判断
单纯查 user.role == "admin" 是静态校验，无法应对“某管理员仅允许管理指定部门用户”这类场景。真实系统中，权限往往和资源实例强绑定。
例如 @app.get("/users/{user_id}") 接口，除了角色判断，还要校验当前用户是否对目标 user_id 有操作权：
- 如果是普通用户，只允许访问自己的
user_id - 如果是部门管理员，需额外查
department_id关联关系 - 如果是超级管理员，才跳过资源归属检查
- 这些逻辑必须在依赖函数里完成，不能拖到业务函数里再做，否则已触发数据库读写或外部调用
别用 fastapi-permissions 这类第三方库处理核心权限流
像 fastapi-permissions 提供了 PermissionsDependency 和 ACL 模型，适合原型验证，但在生产环境容易成为黑盒：
- 它默认把权限规则写死在 Python 对象里，无法热更新；改个权限要重启服务
- 不兼容 SQLAlchemy 异步会话，
await db.execute(...)在它的依赖链里经常报错 - 调试时很难定位是 JWT 解析失败、角色查不到、还是权限比对逻辑出问题
- 建议初期手写依赖函数，等模型稳定后再抽象成可复用的
BasePermissionChecker类
if user.role != "admin": raise HTTPException(...)，而是让权限判断能随业务变化快速响应——比如新增一个“审计员”角色要读取所有日志，但不能修改任何数据，这个角色的权限边界必须能在配置表里改完立刻生效，而不是改代码、测回归、发版上线。 
