502-frameworks-micronaut-rest

Micronaut REST API ガイドライン

Micronaut の HTTP アプリケーションに REST 設計原則を適用します。

このスキルで扱う内容

• @Get/@Post/@Put/@Patch/@Delete と HttpResponse によるステータス制御を使ったセマンティック HTTP
• リソース指向のパスと安定した DTO コントラクト
• Bean Validation によるリクエストボディの @Valid
• エラーの一元的なマッピング（該当する場合は ExceptionHandler／problem JSON）
• Pageable と上限付きサイズによるページネーション
• OpenAPI コントラクトファイル（API ファースト）とサーバースタブ用の OpenAPI Generator
• センシティブなルートへのセキュリティアノテーション（@Secured）
• 再試行される書き込みのための Idempotency-Key
• 楽観的同時実行制御のための ETag／If-Match
• Cache-Control の適切な運用
• API バージョニングのパターン
• DTO での ISO-8601 時刻型

対象範囲： 参照ルールと適切／不適切なコード例に基づいて推奨事項を適用します。

制約

REST のリファクタリング前にコンパイルし、適用後に検証します。

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

このスキルを使用する場面

• Micronaut の @Controller REST API をレビューまたは改善する
• Micronaut HTTP レイヤーでバリデーションやエラーハンドリングを追加する、またはコントローラーを OpenAPI コントラクトに準拠させる
• Micronaut のコントローラーと DTO バリデーションを設計する
• Micronaut の例外ハンドラーと Problem Details レスポンスを追加する
• Micronaut API のページネーション、フィルタリング、または OpenAPI との整合性を改善する

ワークフロー

1. 参照資料を読み、プロジェクトのコンテキストを評価する

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

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

依頼された成果、制約、適用する最小限の安全な変更を特定します。

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

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

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

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

参照資料

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