problem-details-rfc9457

問題詳細 - RFC 9457

エラーコントラクトを選択する

まず、既存のアドバイス、セキュリティのエントリーポイント、API テストを確認してください。API ごとにエラーポリシーを 1 つに統一してください。成功 DTO や成功レスポンスエンベロープは、Problem Details エラーと共存できます。RFC 9457 が規定するのはエラーであり、成功時の表現ではありません。

Problem Details を使用する API では、Spring の組み込み MVC 例外処理を有効にします。

spring:
  mvc:
    problemdetails:
      enabled: true

WebFlux では spring.webflux.problemdetails.enabled とリアクティブな例外処理を使用してください。以下のサーブレット用テンプレートは WebFlux のハンドラーではありません。

ドメインエラー

コンパイル済みの DomainException を ProblemDetailExceptionHandler と組み合わせて使用します。 ハンドラーは、宣言されたステータスと安定したエラーコードを使って、すべてのサブクラスをマッピングします。

• OrderNotFoundException：404。
• InsufficientInventoryException：422。
• BusinessRuleViolationException：422。

各 public クラスには個別のファイルが必要です。これらは HTTP ステータスのメタデータを持つ API 向け例外です。フレームワークに依存しないドメインの場合は、ドメイン例外を独立させ、Web アダプターでマッピングしてください。任意の永続化層やインフラストラクチャの例外メッセージを公開しないでください。

このアドバイスは ResponseEntityExceptionHandler を拡張し、フレームワーク例外に対する Spring の処理を維持します。検証エラーではフィールド違反を含む 400 を返します。予期しない障害では、完全な例外情報をサーバーログにのみ保持し、汎用的な 500 を返します。null 許容の検証メッセージを安全に扱ってください。フィルターレベルの認証失敗には AuthenticationEntryPoint が必要です。認可失敗には AccessDeniedHandler が必要です。コントローラーアドバイスはセキュリティフィルターチェーンを対象としません。メソッドセキュリティ（@PreAuthorize）による拒否は逆のケースです。AccessDeniedException はディスパッチャー内でスローされるため、アドバイスで 403 にマッピングしないと、Exception の包括的なハンドラーが 500 を返します。

レスポンスフィールド

{
  "type": "https://api.example.com/errors/order_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Order not found",
  "instance": "/api/orders/123",
  "errorCode": "ORDER_NOT_FOUND"
}

カスタムの問題タイプには、プロジェクトが管理する安定した URI を使用してください。明示的な type は省略可能です。省略時のデフォルトは about:blank です。その場合、タイトルは HTTP ステータスの文言と一致させてください。HTTP ステータスと本文のステータスは一致している必要があります。JSON の問題には application/problem+json を使用してください。人間向けのメッセージをクライアントに解析させるのではなく、errorCode や violations などの拡張フィールドを使って、機械可読な詳細を提供してください。

検証

ドメインの 404／422、検証エラーの 400、予期しない障害の 500、および不正な JSON や未対応のメソッドなどのフレームワークエラーについて、実際の HTTP レスポンスをテストしてください。コンテンツタイプ、ステータス、安定したエラーコード、スタックトレースや内部メッセージが含まれていないことを検証します。フィルターによる 401／403 は個別にテストしてください。リポジトリの検証フィクスチャは、両方の Boot バージョンについて、これらのテンプレートをそのままインポートします。

公式情報源

• RFC 9457
• Spring MVC のエラーレスポンス

注意点

• エージェントがドメインのスローする例外とは異なる例外クラスを処理している場合は、具体的な例外をテストしてください。
• エージェントが既存のレガシー API に Problem Details を強制している場合は、移行を求められない限り、既存のコントラクトを維持してください。
• エージェントがすべてのエラーに明示的な type を求める場合でも、デフォルトは about:blank です。
• エージェントが成功レスポンスエンベロープと Problem Details を互換性がないものとして扱う場合でも、一貫性が必要なのはエラーポリシーだけです。
• エージェントがフィルター例外の処理をアドバイスに頼っている場合は、セキュリティハンドラーを別途設定してください。
• エージェントが 500 レスポンスに内部例外メッセージを含める場合は、内部でログに記録し、汎用的な詳細を返してください。