📦 Axum Code Review — Axum代码审查

审查流程

• 检查 Cargo.toml —— 注意 axum 版本（0.6 与 0.7+ 模式不同）、Rust edition（2021 与 2024）、tower、tower-http 特性。Edition 2024 改变了 handler 返回类型中 RPIT 的生命周期捕获规则，并移除了自定义 extractor 对 async-trait 的需求。
• 检查路由 —— 路由组织、方法路由、嵌套路由器
• 检查 extractor —— 顺序很重要（body extractor 必须最后）、类型正确
• 检查 state —— 通过 State 共享状态，而非全局可变状态
• 检查错误处理 —— IntoResponse 实现、错误类型

输出格式

以如下格式报告发现：

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

速查表

审查清单

路由

• [ ] 按领域组织路由（为 /api/users、/api/orders 使用嵌套路由器）
• [ ] 为 404 定义了回退 handler
• [ ] 方法路由显式（使用 .get()、.post()，而非 .route() 手动匹配方法）
• [ ] 无路由冲突（路径重叠但 extractor 不同）

Extractor

• [ ] 消耗 body 的 extractor（Json、Form、Bytes）是最后一个参数
• [ ] State 要求 T: Clone —— 通常是 Arc 或直接 Clone 派生
• [ ] Path 参数类型与路由定义匹配
• [ ] Query 字段对可选查询参数使用 Option 并加 #[serde(default)]
• [ ] 自定义 extractor 实现 FromRequestParts（非 body）或 FromRequest（body）
• [ ] Edition 2024：自定义 extractor 在 trait 实现中使用原生 async fn（FromRequest/FromRequestParts 不再需要 #[async_trait]）

状态管理

• [ ] 应用状态通过 State 共享，而非全局可变静态变量
• [ ] 数据库连接池放在 state 中（而非每次请求新建）
• [ ] state 仅包含共享资源（连接池、配置、通道），不含请求特定数据
• [ ] state 类型已派生 Clone 或手动实现
• [ ] Edition 2024：共享静态状态使用 std 的 LazyLock（而非 once_cell::sync::Lazy 或 lazy_static!）

错误处理

• [ ] handler 错误实现 IntoResponse 以返回正确 HTTP 错误码
• [ ] 内部错误不泄露给客户端（500 响应中不含原始错误信息）
• [ ] 错误响应使用统一格式（JSON 错误体含 code/message）
• [ ] handler 使用 Result 模式
• [ ] Edition 2024：handler 返回类型 -> impl IntoResponse 默认捕获所有作用域生命周期；返回 owned 数据时可用 + use<> 选择不捕获请求生命周期

中间件

• [ ] Tower 层按正确顺序应用（外层在请求时先执行，响应时最后执行）
• [ ] 使用 tower-http 处理常见需求（CORS、压缩、tracing、超时）
• [ ] 请求作用域数据通过 extension 传递，而非全局状态
• [ ] 中间件错误不 panic —— 而是返回错误响应
• [ ] Edition 2024：使用 #[async_trait] 的中间件可迁移到 trait 实现中的原生 async fn

严重级别校准

Critical

• body extractor 不在 handler 参数最后（静默消耗 body，后续 extractor 失败）
• 通过路径/查询参数直接拼接导致 SQL 注入
• 内部错误细节泄露给客户端（堆栈、数据库错误）
• 受保护路由缺少认证中间件

Major

• 使用全局可变状态而非 State（竞态条件）
• 缺少错误类型转换（直接向客户端返回原始 sqlx::Error）
• 缺少请求超时（handler 可能无限挂起）
• 路由冲突导致意外 405
• Edition 2024：FromRequest/FromRequestParts 仍使用 async-trait，而原生 async fn 已可用

Minor

• 手动路由方法匹配而非 .get()、.post()
• 缺少回退 handler（默认 404 为纯文本而非 JSON）
• 中间件按路由单独应用，而本应全局（或反之）
• 缺少 tower-http::trace 记录请求日志
• Edition 2024：在可用 std::sync::LazyLock 的地方仍使用 once_cell::sync::Lazy 或 lazy_static!

Informational

• 建议使用 tower-http 层处理常见需求
• 路由器组织改进
• 建议通过 utoipa 或 aide 添加 OpenAPI 文档

有效模式（勿标记）

• #[axum::debug_handler] 作用于 handler —— 调试辅助，改善编译错误信息
• Extension 用于中间件注入数据 —— 请求作用域值的合法模式
• 从 handler 返回 impl IntoResponse —— 比具体类型更灵活
• 每模块使用 Router::new()，在主函数合并 —— 标准组织模式
• ServiceBuilder 用于层组合 —— Tower 模式，非过度设计
• axum::serve 搭配 TcpListener —— axum 0.7+ 标准服务器启动方式
• 在 FromRequest/FromRequestParts 实现中使用原生 async fn —— 不再需要 async-trait crate（Rust 1.75 起稳定）
• handler 返回类型使用 + use<'a> —— Edition 2024 对 RPIT 的精确捕获语法
• 使用 std::sync::LazyLock 做共享静态状态 —— 替代 once_cell/lazy_static（Rust 1.80 起稳定）

提交发现前

加载并遵循 beagle-rust:review-verification-protocol 后再报告任何问题。