ln-772-error-handler-setup

ln-772-error-handler-setup

タイプ: L3 ワーカー カテゴリ: 7XX プロジェクトのブートストラップ

.NET および Python のバックエンドアプリケーション向けに、グローバルエラーハンドリングを設定します。

---

概要

項目	詳細
入力	ln-770 のコンテキストストア
出力	例外処理ミドルウェアとカスタム例外
スタック	.NET（ASP.NET Core ミドルウェア）、Python（FastAPI 例外ハンドラー）

---

フェーズ 1：コンテキストを受け取る

コーディネーターからコンテキストストアを受け取ります。

必須コンテキスト：

• STACK：.NET または Python
• FRAMEWORK：ASP.NET Core または FastAPI
• PROJECT_ROOT：プロジェクトディレクトリのパス
• ENVIRONMENT：Development または Production

冪等性チェック：

• .NET：GlobalExceptionMiddleware または UseExceptionHandler を grep します
• Python：@app.exception_handler または exception_handlers.py を grep します
• 見つかった場合：{ "status": "skipped" } を返します

---

フェーズ 2：エラーハンドリングのパターンを調査する

MCP ツールを使用して、最新のドキュメントを取得します。

.NET の場合：

MCP ref: "ASP.NET Core global exception handling middleware"
Context7: /dotnet/aspnetcore

Python の場合：

MCP ref: "FastAPI exception handlers custom exceptions"
Context7: /tiangolo/fastapi

調査する主なパターン：

1. ミドルウェアパイプライン内での配置
2. 例外型と HTTP ステータスコードのマッピング
3. ProblemDetails（RFC 7807）形式
4. Development と Production でのエラー詳細
5. ロギングの統合

---

フェーズ 3：決定事項

Q1：エラーレスポンス形式

オプション	説明
ProblemDetails（RFC 7807）（推奨）	標準化された形式で、広く採用されています
カスタム形式	プロジェクト固有の要件

Q2：エラー詳細のレベル

環境	スタックトレース	内部例外	リクエストの詳細
Development	✓ 表示	✓ 表示	✓ 表示
Production	✗ 非表示	✗ 非表示	✗ 非表示

Q3：エラー分類

標準エラーコードを定義します。

コード	HTTP ステータス	説明
VALIDATION_ERROR	400	入力データが無効です
UNAUTHORIZED	401	認証が必要です
FORBIDDEN	403	権限が不足しています
NOT_FOUND	404	リソースが見つかりません
CONFLICT	409	リソースの状態が競合しています
INTERNAL_ERROR	500	予期しないサーバーエラーです

---

フェーズ 4：設定を生成する

.NET の出力ファイル

ファイル	用途
Middleware/GlobalExceptionMiddleware.cs	例外処理ミドルウェア
Exceptions/AppException.cs	基底例外クラス
Exceptions/ValidationException.cs	入力検証エラー
Exceptions/NotFoundException.cs	リソース未検出エラー
Models/ErrorResponse.cs	エラーレスポンスモデル

生成プロセス：

1. MCP ref を使用して、最新の ASP.NET Core 例外処理パターンを取得します
2. 以下を含む GlobalExceptionMiddleware を生成します。
   • 例外型と HTTP ステータスのマッピング
   • 例外のロギング
   • ProblemDetails レスポンス形式
   • 環境に応じた詳細レベル
3. カスタム例外クラスを生成します

登録コード：

app.UseMiddleware<GlobalExceptionMiddleware>();

Python の出力ファイル

ファイル	用途
exceptions/app_exceptions.py	カスタム例外クラス
exceptions/handlers.py	FastAPI 例外ハンドラー
models/error_response.py	Pydantic エラーモデル

生成プロセス：

1. MCP ref を使用して、最新の FastAPI 例外処理パターンを取得します
2. 以下を含む例外ハンドラーを生成します。
   • HTTPException の処理
   • カスタム AppException の処理
   • 入力検証エラーの処理
   • リクエスト検証エラーの処理
3. カスタム例外クラスを生成します

登録コード：

app.add_exception_handler(AppException, app_exception_handler)
app.add_exception_handler(RequestValidationError, validation_exception_handler)

---

フェーズ 5：検証する

検証手順：

1. 構文チェック：

   • .NET：dotnet build --no-restore
   • Python：python -m py_compile exceptions/handlers.py

2. エラーハンドリングをテストする：

   • 例外をスローするテストエンドポイントを作成します
   • エラーレスポンス形式を確認します
   • Production でスタックトレースが非表示になっていることを確認します

エラーレスポンスの例（ProblemDetails）：

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input data",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ],
  "traceId": "abc-123-def-456"
}

---

コーディネーターへの返却

{
  "status": "success",
  "files_created": [
    "Middleware/GlobalExceptionMiddleware.cs",
    "Exceptions/AppException.cs",
    "Models/ErrorResponse.cs"
  ],
  "packages_added": [],
  "registration_code": "app.UseMiddleware<GlobalExceptionMiddleware>();",
  "message": "Configured global exception handling"
}

---

参照リンク

• ASP.NET Core のエラー処理
• FastAPI のエラー処理
• RFC 7807 Problem Details

---

重要なルール

• デフォルトで ProblemDetails（RFC 7807）を使用する — 標準化されたエラーレスポンス形式です
• 本番環境ではスタックトレースを隠す — 環境に応じた詳細レベルの設定が必須です
• 現在のパターンには MCP ref を使用する — 記憶を頼りにミドルウェアをハードコードしないでください
• 冪等にする — GlobalExceptionMiddleware または exception_handlers.py が存在する場合は、status: "skipped" を返します
• すべてのカスタム例外を HTTP ステータスコードにマッピングする — 未処理の例外型をクライアントに到達させないでください

完了の定義

• コンテキストストアを受信済み（スタック、フレームワーク、環境）
• MCP ツールを使用してエラー処理パターンを調査済み
• GlobalExceptionMiddleware（.NET）または例外ハンドラー（Python）を生成済み
• カスタム例外クラス（AppException、ValidationException、NotFoundException）を作成済み
• エラーレスポンスモデル（ProblemDetails 形式）を作成済み
• 構文を検証済み（dotnet build または py_compile）
• 構造化 JSON レスポンスを ln-770 コーディネーターに返却済み

---

バージョン： 2.0.0 最終更新日： 2026-01-10