CR-FASTAPI-006: Error Handling Unification（エラー標準化） - 完了レポート

実装日時

2025年12月3日

概要

目的

FastAPI 全 API で返すエラーを 1つの標準構造に統一する。 既存の Flask 依存コードは壊さず、新規 FastAPI 層のみ対象。

ゴール

  • すべてのエンドポイントで統一されたエラーレスポンス形式を実装
  • make_error() 関数によるエラーハンドリングの統一
  • OpenAPI スキーマにエラーレスポンスを追加
  • エラーコード命名規則の統一

原則

  • すべてのエラーは ErrorResponse モデルに準拠
  • HTTPException を直接返さず、make_error() を使用
  • OpenAPI スキーマにすべてのエラーレスポンスを定義
  • 既存の Flask 実装には影響を与えない

実装ステップ

Step 1: エラービルダー関数の作成

作成ファイル: src/nexuscore/api/utils/errors.py

実装内容:

  • make_error(): 統一されたエラーレスポンスを生成する基本関数
  • make_not_found_error(): 404 エラー用のショートカット関数
  • make_unauthorized_error(): 401 エラー用のショートカット関数
  • make_validation_error(): 422 エラー用のショートカット関数
  • make_internal_error(): 500 エラー用のショートカット関数
  • make_bad_request_error(): 400 エラー用のショートカット関数
  • make_forbidden_error(): 403 エラー用のショートカット関数
  • make_conflict_error(): 409 エラー用のショートカット関数

実装理由:

  • すべてのエラーを統一された形式で生成するため
  • エラーコードとメッセージを明確に定義するため
  • 再利用可能なショートカット関数を提供するため

Step 2: すべてのルータでエラーハンドリングを統一

変更ファイル:

  • src/nexuscore/api/routes/execute.py
  • src/nexuscore/api/routes/github_webhook.py
  • src/nexuscore/api/routes/projects.py
  • src/nexuscore/api/routes/runs.py
  • src/nexuscore/api/routes/plans.py
  • src/nexuscore/api/dependencies/auth.py

変更内容:

  • すべての raise HTTPException(...) を raise make_error(...) に置換
  • エラーコードを統一された命名規則に従って設定
  • エラーメッセージを明確化

エラーコード命名規則:

  • NOT_FOUND: 404 - リソース未検出
  • UNAUTHORIZED: 401 - API Key 不正
  • VALIDATION_ERROR: 422 - バリデーション不正
  • INTERNAL_ERROR: 500 - サーバー内部エラー
  • INVALID_REQUEST: 400 - パラメータ不正
  • FORBIDDEN: 403 - 権限なし
  • CONFLICT: 409 - 既存・重複エラー

Step 3: OpenAPI スキーマにエラーレスポンスを追加

変更ファイル:

  • src/nexuscore/api/routes/execute.py
  • src/nexuscore/api/routes/github_webhook.py
  • src/nexuscore/api/routes/projects.py
  • src/nexuscore/api/routes/runs.py
  • src/nexuscore/api/routes/plans.py
  • src/nexuscore/api/routes/health.py

変更内容:

  • すべてのエンドポイントに responses パラメータを追加
  • 4xx/5xx エラーレスポンスに ErrorResponse モデルを指定

例:

@router.get(
    "/projects/{project_id}",
    response_model=ProjectResponse,
    responses={
        401: {"model": ErrorResponse},
        404: {"model": ErrorResponse},
        500: {"model": ErrorResponse},
    },
)

Step 4: テストの作成

作成ファイル: tests/api/test_fastapi_errors.py

テスト内容:

  • test_not_found_error_format: NotFound エラーの形式確認
  • test_unauthorized_error_format: Unauthorized エラーの形式確認
  • test_validation_error_format: ValidationError の形式確認
  • test_internal_error_format: InternalError の形式確認
  • test_error_schemas_in_openapi: OpenAPI スキーマにエラースキーマが定義されていることを確認
  • test_all_endpoints_have_error_responses: すべてのエンドポイントにエラーレスポンスが定義されていることを確認

実装理由:

  • 統一されたエラー形式が正しく実装されていることを確認
  • OpenAPI スキーマにエラーレスポンスが含まれていることを確認
  • すべてのエンドポイントでエラーハンドリングが統一されていることを確認

変更ファイル一覧

新規作成ファイル

  • src/nexuscore/api/utils/errors.py - エラービルダー関数
  • tests/api/test_fastapi_errors.py - エラーハンドリング統一のテスト

変更ファイル

  • src/nexuscore/api/routes/execute.py - エラーハンドリングの統一、OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/routes/github_webhook.py - エラーハンドリングの統一、OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/routes/projects.py - エラーハンドリングの統一、OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/routes/runs.py - エラーハンドリングの統一、OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/routes/plans.py - エラーハンドリングの統一、OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/routes/health.py - OpenAPI スキーマにエラーレスポンス追加
  • src/nexuscore/api/dependencies/auth.py - エラーハンドリングの統一

変更なし（既存実装を再利用）

  • src/nexuscore/api/schemas/error.py - 既存の ErrorResponse モデルを使用（変更なし）

動作確認結果

静的解析結果

  • リンターエラー: なし
  • 型チェック: 問題なし

テスト結果

実行コマンド:

source myenv_linux/bin/activate
export PYTHONPATH=/home/yn441611/NexusCore/src:$PYTHONPATH
export NEXUSCORE_API_KEY=test-api-key-123
python -m pytest tests/api/test_fastapi_errors.py -v

結果:

  • エラーハンドリング統一のテスト: 6個のテストケースを実装
  • すべてのテストが正常に通過（モックベースのテスト）

確認項目:

  • ✅ NotFound エラーが統一された形式で返される
  • ✅ Unauthorized エラーが統一された形式で返される
  • ✅ ValidationError が統一された形式で返される
  • ✅ InternalError が統一された形式で返される
  • ✅ OpenAPI スキーマに ErrorResponse と ErrorDetail が定義されている
  • ✅ すべてのエンドポイントにエラーレスポンスが定義されている

コードレビュー結果

  • ✅ .cursorrules のルールに準拠
  • ✅ すべてのエラーが make_error() を使用
  • ✅ OpenAPI スキーマにエラーレスポンスが含まれている
  • ✅ 既存の Flask 実装に影響なし
  • ✅ 統一されたエラーコード命名規則に従っている

設計上の改善点

アーキテクチャの改善

  1. エラーハンドリングの統一
    • すべてのエンドポイントで統一されたエラー形式
    • make_error() 関数による一貫性の確保
    • エラーコードとメッセージの明確化
  2. OpenAPI スキーマの完全性
    • すべてのエラーレスポンスが OpenAPI スキーマに定義
    • クライアントがエラーレスポンスを事前に把握可能
    • API ドキュメントの自動生成が可能
  3. 再利用可能なエラービルダー関数
    • ショートカット関数による開発効率の向上
    • エラーコードの一貫性の確保
    • メンテナンス性の向上

将来の拡張性への配慮

  1. カスタムエラーハンドラーの追加
    • 将来的にカスタムエラーハンドラーを追加可能
    • FastAPI の例外ハンドラーと統合可能
  2. エラーコードの拡張
    • 新しいエラーコードを簡単に追加可能
    • エラーコードの命名規則を維持
  3. 多言語対応
    • エラーメッセージの多言語対応が可能
    • エラーメッセージの構造化が容易

コード品質の向上

  1. 一貫性の確保
    • すべてのエンドポイントで統一されたエラー形式
    • エラーコードの命名規則の統一
    • エラーメッセージの明確化
  2. 保守性の向上
    • エラーハンドリングロジックの集約
    • 再利用可能な関数の提供
    • テストの追加による品質保証
  3. ドキュメント化
    • OpenAPI スキーマによる自動ドキュメント生成
    • エラーレスポンスの明確な定義
    • API クライアントの開発を支援

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存の Flask アプリケーションには影響なし
  • ✅ 既存のデータベースモデルを再利用
  • ✅ 既存のFlask実装と同じエラーメッセージ形式

制限事項やトレードオフ

  1. FastAPI のデフォルトバリデーションエラー
    • FastAPI のデフォルトバリデーションエラー（422）は、統一された形式とは異なる
    • カスタムエラーハンドラーを追加することで統一可能（将来の拡張）
  2. エラーメッセージの多言語対応
    • 現時点では英語のみ対応
    • 将来的に多言語対応を追加可能
  3. エラーコードの拡張
    • 新しいエラーコードを追加する場合は、命名規則に従う必要がある
    • エラーコードの一貫性を維持する必要がある

移行時の注意点

  • FastAPI アプリは既存の Flask アプリとは別ポートで実行可能
  • 既存の API クライアントは統一されたエラー形式に対応する必要がある
  • エラーレスポンスの構造が変更されたため、クライアント側の更新が必要な場合がある

次のステップ

推奨されるフォローアップアクション

  1. カスタムエラーハンドラーの追加
    • FastAPI の例外ハンドラーを追加して、デフォルトバリデーションエラーも統一された形式に変換
    • 未処理の例外を統一された形式で返す
  2. エラーメッセージの多言語対応
    • エラーメッセージの多言語対応を追加
    • Accept-Language ヘッダーに基づく言語選択
  3. エラーコードの拡張
    • 新しいエラーコードを追加（例: RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE）
    • エラーコードの命名規則を維持
  4. エラーロギングの改善
    • エラー発生時のロギングを改善
    • エラー追跡のための correlation ID の追加
  5. ドキュメント整備
    • エラーコード一覧のドキュメント化
    • エラーレスポンスの使用例の追加

関連ドキュメント

まとめ

CR-FASTAPI-006 の実装により、FastAPI 全 API で統一されたエラーハンドリングが完成しました。すべてのエンドポイントで make_error() 関数を使用し、統一されたエラー形式を実現しました。OpenAPI スキーマにすべてのエラーレスポンスが定義され、API クライアントがエラーレスポンスを事前に把握できるようになりました。

すべてのテストが成功し、.cursorrules のルールに準拠した実装が完了しています。

This site uses Just the Docs, a documentation theme for Jekyll.