302-frameworks-spring-boot-rest

Java REST API 設計原則

Spring Boot アプリケーションに REST API 設計原則を適用します。

このスキルで扱う内容

• HTTP メソッド（GET、POST、PUT、PATCH、DELETE）— 意味の一貫性
• リソース URI の設計
• HTTP ステータスコード
• 簡潔な契約を実現するリクエスト／レスポンス DTO
• API バージョニング（URI、ヘッダー、メディアタイプのいずれかを一貫して適用）
• 境界での Bean Validation（コントローラーの入力に @Valid/@Validated を適用し、失敗時は 400 を返す）
• ページネーション、並べ替え、フィルタリング（上限を設定した Page/Pageable）
• JSON 契約でのオフセット付き ISO-8601 インスタント（OffsetDateTime、Instant）
• コンテンツネゴシエーション（デフォルトは JSON。適切な場合はベンダーメディアタイプを使用）
• POST による作成での Idempotency-Key のサポート。競合時は 409 Conflict を返す
• If-Match/If-None-Match による ETag の同時実行制御。412 Precondition Failed／304 Not Modified
• HTTP キャッシュの適切な運用（Cache-Control、ETag、Last-Modified）
• 非推奨化および提供終了を示すヘッダー（Deprecation、Sunset、Link rel="successor-version"）
• エラー処理
• API セキュリティ（TLS、認証、認可、入力検証）
• API 契約：API ファーストでは OpenAPI ファイルを信頼できる唯一の情報源として使用（OpenAPI Generator）
• Controller advice と Problem Details（RFC 7807）

範囲： リファレンスのルールと良い／悪いコード例に基づいて推奨事項を適用します。

制約

REST API の変更を適用する前に、プロジェクトがコンパイルできることを確認してください。コンパイルに失敗した場合は、ただちに作業を中止してください。改善を適用した後は、全体の検証を実行してください。

• 必須： 変更を適用する前に ./mvnw compile または mvn compile を実行する
• 安全性： コンパイルに失敗した場合は、ただちに作業を中止する
• 検証： 改善を適用した後に ./mvnw clean verify または mvn clean verify を実行する
• 適用前： 詳細なルールと良い／悪いパターンについて、リファレンスを読む
• エッジケース： 依頼の範囲が曖昧な場合は、変更を適用する前に作業を中止し、確認を求める
• エッジケース： 必要な入力、ファイル、またはツールが不足している場合は、不足しているものを報告し、セットアップの案内を進めてよいか確認する

このスキルを使う場面

• Spring Boot REST API の Java コードをレビューする
• Java コードで Spring Boot REST API のベストプラクティスを適用する
• Spring Boot の REST コントローラーと DTO を設計する
• Spring Boot REST に Problem Details エラーレスポンスを追加する
• Spring API のページネーション検証や冪等性を改善する

ワークフロー

1. リファレンスを読み、プロジェクトのコンテキストを把握する

変更を提案する前に、references/302-frameworks-spring-boot-rest.md を読み、現在のプロジェクト設定を確認します。

2. 範囲を把握し、対象とする改善を決める

依頼された結果、制約、適用する変更のうち安全上必要な最小限の範囲を特定します。

3. フレームワークに沿った変更を適用する

リファレンスのパターンとプロジェクトの規約に従って、設定やコードを実装またはリファクタリングします。

4. 検証を実行し、結果を報告する

適切なビルドやテストを実行し、変更内容、検証内容、今後必要な対応を要約します。

リファレンス

詳細なガイダンス、例、制約については、references/302-frameworks-spring-boot-rest.md を参照してください。