402-frameworks-quarkus-rest

Quarkus REST API ガイドライン

Jakarta REST（JAX-RS）を使用して、Quarkus に REST API 設計の原則を適用します。

このスキルの対象範囲

• リソースクラス、@Path、HTTP メソッドのマッピング、リソース URI の設計
• ステータスコード、Location ヘッダー、Response の構築
• 境界での DTO と Bean Validation、日付／時刻フィールドの ISO-8601
• 一貫性のあるエラー JSON（RFC 7807 Problem Details）を実現する ExceptionMapper
• API のバージョニング戦略（URI パス、Accept ヘッダー）
• Idempotency-Key ヘッダーによる冪等性
• 楽観的同時実行制御：ETag、If-Match、If-None-Match
• Cache-Control ヘッダーによる HTTP キャッシュ
• API の非推奨化：Sunset ヘッダーと Deprecation ヘッダー
• ページネーション、ソート、フィルタリングのクエリパラメーター
• SmallRye によるオプションの /openapi、openapi.yaml で維持する API ファーストのコントラクト（コード生成）
• リアクティブとブロッキングの考慮事項、@RunOnVirtualThread
• フィルターレイヤーでのセキュリティ統合

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

制約

REST の変更を適用する前に、プロジェクトがコンパイルできることを確認してください。改善を適用した後は、完全な検証を実行してください。

• 必須：変更を適用する前に、./mvnw compile または mvn compile を実行してください
• 前提条件：REST API の改善を適用する前に、プロジェクトがコンパイルできる必要があります
• 安全性：コンパイルに失敗した場合は、直ちに停止してください
• ブロッキング条件：コンパイルエラーは、先に進む前にユーザーが解決する必要があります
• 検証：改善を適用した後、./mvnw clean verify または mvn clean verify を実行してください
• 適用前：詳細なルールと例について、参照資料を読んでください

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

• Quarkus プロジェクトの JAX-RS リソースをレビューまたは改善する
• Quarkus でバリデーションとエラー処理を備えた HTTP API を設計する
• API のバージョニング、冪等性、ETag による同時実行制御、または非推奨化ヘッダーを追加する
• ページネーション、ソート、または RFC 7807 Problem Details によるエラーレスポンスを実装する
• Quarkus の REST リソースと例外マッパーを改善する

ワークフロー

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

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

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

求められている成果、制約、適用する変更のうち安全な最小限の範囲を特定します。

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

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

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

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

参照資料

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