axum-code-review

Axum コードレビュー

レビューワークフロー

1. Cargo.toml を確認する — axum のバージョン（0.6 と 0.7 以降ではパターンが異なります）、Rust エディション（2021 と 2024）、tower、tower-http の機能を確認します。Edition 2024 では、ハンドラーの戻り値の型における RPIT のライフタイムキャプチャが変更され、カスタムエクストラクターで async-trait を使う必要がなくなります。
2. ルーティングを確認する — ルートの構成、メソッドルーティング、ネストしたルーター
3. エクストラクターを確認する — 順序が重要です（ボディを扱うエクストラクターは最後に配置します）。型も確認します。
4. 状態を確認する — グローバルな可変状態ではなく、State<T> を使って共有します。
5. エラー処理を確認する — IntoResponse の実装、エラー型

ゲート（指摘事項を報告する前に）

順番に実行してください。該当する手順を通過するまで、指摘事項を書いてはいけません。

1. ディスク上のバージョンとエディション — 合格条件： 該当する Cargo.toml（クレートまたはワークスペースのルート）を読み、axum（および関連する tower／tower-http）のバージョンと Rust の edition を明示できます。そのうえで、そのファイルの内容に基づく場合に限り、0.6 と 0.7 以降の違いや Edition 2024 固有のチェック項目を適用します。

2. 指摘事項ごとの根拠 — 合格条件： 各問題について、レビュー対象のハンドラー、ルーター、レイヤー、型を示す、現在のツリーにある [FILE:LINE] を引用しています（記憶、ドキュメントのみ、別ブランチからの引用は不可）。

3. プロトコルに照らしたカテゴリーチェック — 合格条件： 指摘の種類（ルーティングの競合、エクストラクターの順序、エラー漏えい、ミドルウェアの順序など）に応じて、review-verification-protocol スキルの該当するチェックを実行しています（例：エクストラクターの順序を確認するためにハンドラーのシグネチャ全体を確認する、「生のエラーをクライアントに返している」と指摘する前に、周辺のエラーマッピングを確認する）。そのうえで指摘事項を追加します。

4. 出力形式 — 合格条件： レポートの行が、以下の出力形式（重要度＋説明）に一致しています。

出力形式

指摘事項は次の形式で報告してください。

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

クイックリファレンス

問題の種類	参照先
ルート定義、ネスト、メソッドルーティング	references/routing.md
State、Path、Query、Json、ボディエクストラクター	references/extractors.md
Tower ミドルウェア、レイヤー、エラー処理	references/middleware.md

レビューチェックリスト

ルーティング

• ドメインごとにルートを整理している（/api/users、/api/orders にはネストしたルーターを使用）
• 404 用のフォールバックハンドラーを定義している
• メソッドルーティングを明示している（手動でメソッドを判定する .route() ではなく、.get()、.post() を使用）
• ルートの競合がない（異なるエクストラクターを使うパスの重複）

エクストラクター

• ボディを消費するエクストラクター（Json、Form、Bytes）を最後のパラメーターにしている
• State<T> では T: Clone が必要です。通常は Arc<AppState> を使うか、直接 Clone を derive します
• Path<T> のパラメーター型がルート定義と一致している
• #[serde(default)] を使い、任意のクエリパラメーターに対応する Query<T> のフィールドを Option にしている
• カスタムエクストラクターが FromRequestParts（ボディを扱わない場合）または FromRequest（ボディを扱う場合）を実装している
• Edition 2024：カスタムエクストラクターはトレイト実装内でネイティブの async fn を使用している（FromRequest／FromRequestParts では #[async_trait] は不要です）

状態管理

• グローバルな可変 static ではなく、State<T> を使ってアプリケーションの状態を共有している
• データベースプールを状態に保持している（リクエストごとに作成していない）
• 状態に含めるのは共有リソース（プール、設定、チャネル）のみであり、リクエスト固有のデータは含めていない
• 状態型に Clone を derive するか、手動で実装している
• Edition 2024：共有 static 状態に once_cell::sync::Lazy や lazy_static! ではなく、std の LazyLock を使用している

エラー処理

• ハンドラーのエラーで IntoResponse を実装し、適切な HTTP エラーコードを返す
• 内部エラーをクライアントに漏らさない（500 レスポンスに生のエラーメッセージを含めない）
• エラーレスポンスの形式を統一する（コードとメッセージを含む JSON エラーボディ）
• ハンドラーで Result<impl IntoResponse, AppError> パターンを使用する
• Edition 2024：ハンドラーの戻り値の型 -> impl IntoResponse は、デフォルトですべてのスコープ内のライフタイムをキャプチャします。所有データを返す際にリクエストのライフタイムをキャプチャしないようにするには、+ use<> を使用します

ミドルウェア

• Tower レイヤーを正しい順序で適用する（リクエストでは外側が先に実行され、レスポンスでは最後に実行されます）
• 一般的な関心事（CORS、圧縮、トレース、タイムアウト）には tower-http を使用する
• リクエストスコープのデータはグローバル状態ではなく、エクステンション経由で渡す
• ミドルウェアのエラーでパニックを起こさず、エラーレスポンスを返す
• Edition 2024：#[async_trait] を使用するミドルウェアは、トレイト実装でネイティブの async fn に移行できます

重大度の基準

重大

• ハンドラーのパラメーターでボディ抽出器が最後にない（ボディを暗黙に消費し、後続の抽出器が失敗します）
• パス／クエリパラメーターをクエリに直接渡すことによる SQL インジェクション
• 内部エラーの詳細がクライアントに漏れる（スタックトレース、データベースエラー）
• 保護対象のルートに認証ミドルウェアがない

重要

• State<T> の代わりにグローバルな可変状態を使用している（競合状態が発生します）
• エラー型の変換がない（生の sqlx::Error がクライアントに返されます）
• リクエストのタイムアウトがない（ハンドラーが無期限に停止する可能性があります）
• ルートの競合により予期しない 405 が発生する
• Edition 2024：ネイティブの async fn が使える FromRequest／FromRequestParts に、引き続き async-trait を使用している

軽微

• .get()、.post() の代わりに手動でルートのメソッドを照合している
• フォールバックハンドラーがない（デフォルトの 404 は JSON ではなくプレーンテキストです）
• グローバルに適用すべき（またはその逆の）ミドルウェアをルートごとに適用している
• リクエストのロギングに tower-http::trace を使用していない
• Edition 2024：std::sync::LazyLock が使用可能な箇所で once_cell::sync::Lazy または lazy_static! を使用している

情報

• 一般的な関心事に tower-http レイヤーを使用する提案
• ルーター構成の改善
• utoipa または aide による OpenAPI ドキュメントの追加提案

問題として報告しない有効なパターン

• ハンドラーでの #[axum::debug_handler] の使用 — コンパイルエラーメッセージを改善するデバッグ補助機能です
• ミドルウェアが注入するデータへの Extension<T> の使用 — リクエストスコープの値に有効なパターンです
• ハンドラーからの impl IntoResponse の返却 — 具体的な型よりも柔軟です
• モジュールごとに Router::new() を作成し、メインでマージする構成 — 標準的な構成パターンです
• レイヤーの構成に ServiceBuilder を使用すること — Tower のパターンであり、過剰な設計ではありません
• TcpListener を使った axum::serve — axum 0.7 以降の標準的なサーバー設定です
• FromRequest／FromRequestParts の実装でのネイティブ async fn — async-trait クレートは不要になりました（Rust 1.75 以降で安定版です）
• ハンドラーの戻り値の型での + use<'a> — RPIT における Edition 2024 の正確なキャプチャ構文です
• 共有する静的状態への std::sync::LazyLock の使用 — once_cell／lazy_static を置き換えます（Rust 1.80 以降で安定版です）

指摘事項を提出する前に

問題を確定する前に、**ゲート（指摘事項の報告前）**を完了し、カテゴリ固有の確認のために review-verification-protocol スキルを読み込んでください。