FastAPI 代码审查

快速参考

审查清单

• 使用正确的 prefix 和 tags 配置 APIRouter
• 所有路由均明确指定 response_model 以保障类型安全
• 使用正确的 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
• 正确设置状态码（如 200、201、204、404 等）
• 依赖项使用 Depends() 注入，而非手动调用
• yield 依赖具备恰当的清理逻辑
• 请求/响应模型均基于 Pydantic 定义
• 使用 HTTPException 并显式指定状态码与 detail 信息
• 所有路由处理器均为 async def
• 不包含阻塞式 I/O 操作（如 requests、time.sleep、open()）
• 非阻塞操作通过后台任务（background tasks）执行
• 路由处理器中不使用裸 except 语句

有效模式（请勿标记）

以下为 FastAPI 的惯用模式，表面看似有问题，实则正确：

• Pydantic 自动校验请求体 —— 当参数为带类型注解的 Pydantic 模型时，无需额外手动校验
• 数据库会话通过依赖注入获取 —— 会话应来自 Depends()，而非作为函数参数显式传入
• 所有 HTTP 错误统一使用 HTTPException —— FastAPI 会自动将其转换为标准 HTTP 响应
• async def 路由处理器中未使用 await —— 可能依赖同步依赖或执行简单操作；FastAPI 可正常处理此类情况
• Depends() 上的类型注解 —— 仅用于文档说明或 IDE 支持，并非运行时类型断言
• Query/Path/Body 参数的默认值 —— FastAPI 在运行时解析这些默认值，而非采用传统 Python 默认参数机制
• 路由处理器返回 dict —— 若已设置 response_model，Pydantic 将自动完成序列化转换

上下文敏感规则

仅在上下文确实存在问题时才进行标记：

• 仅当字段未被 Pydantic 模型及其验证器覆盖时，才标记“缺少校验”
• 仅当端点未使用 Depends() 注入认证依赖时，才标记“缺少认证”
• 仅当错误场景下未恰当抛出 HTTPException 时，才标记“缺少错误处理”
• 仅当实际存在阻塞操作（如文件 I/O、网络调用、CPU 密集型任务）时，才标记“异步中混用同步代码”，而非仅因代码未使用 async/await

守门检查（FastAPI 特定）

针对每个 FastAPI 相关发现，**仅执行一次**，且须在可锚定该处理器的 **file:line**（参见 review-verification-protocol）之后、发现内容正式提交之前执行。若任一检查步骤未满足通过条件，则**不得**直接按原样断言该发现——应收集证据、撤回、降级严重性，或改述为疑问形式。

守门检查 1 — 路由装饰器与响应面

守门检查 2 — 阻塞式操作或“应为异步”

守门检查 3 — Depends、校验、认证

FastAPI 框架行为特性

FastAPI + Pydantic 可自动处理多项关键关注点：

• 通过 Pydantic 模型实现请求校验
• 通过 response_model 实现响应序列化
• 通过依赖注入支持横切关注点（cross-cutting concerns）
• 通过异常处理器（exception handlers）统一处理异常

在标记某项功能“缺失”前，请先确认 FastAPI 是否已在底层自动处理。

何时加载参考文档

• 审查路由定义 → 查阅 routes.md
• 审查依赖注入 → 查阅 dependencies.md
• 审查 Pydantic 模型与校验逻辑 → 查阅 validation.md
• 审查异步路由处理器 → 查阅 async.md

审查问题清单

1. 所有路由是否都显式声明了 response_model 和状态码？
2. 依赖项是否通过 Depends() 注入，并具备正确的清理逻辑？
3. 所有 Pydantic 模型是否能正确校验输入？
4. 所有路由处理器是否均为异步且无阻塞操作？

提交发现前须完成事项

1. 对每个 FastAPI 相关发现，须完整执行上述 守门检查（FastAPI 特定）。
2. 提交任何问题前，须加载并严格遵循 review-verification-protocol（含 Pre-Report checklist 及 Verification by Issue Type）。