spring-mvc-webflux-api-builder

Spring MVC WebFlux API ビルダー

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-06）から派生した Tier 1 の重要スキルです。

ミッション

リポジトリで実際に使用されている Spring スタックに対して、もっともらしいだけでなく正しい API コードを生成します。 エンドポイント、DTO、バリデーション、テストのひな形を、まとまりのある一式として生成します。

まずスタックを判断する

• モジュールが Spring MVC か WebFlux かを確認します。
• コントローラーがブロッキング方式、コルーチン方式、Reactor 方式のいずれかを確認します。
• プロジェクトで既に採用されているエラー形式、シリアライズ規則、OpenAPI のアプローチを確認します。
• これらの事実が project-context-ingestion の出力で既に明らかになっている場合は、それを再利用します。

コードを書く前にコントラクトを設計する

• エンドポイントのパス、メソッド、認証要件、冪等性のルール、ステータスコードを定義します。
• リクエストとレスポンスの DTO の境界を定義します。エンティティを直接公開しないでください。
• バリデーション失敗、ビジネス上の競合、未検出、予期しないエラーに対するエラーモデルを定義します。
• 該当する場合は、ページネーション、ソート、相関 ID の動作を定義します。
• null、未指定、デフォルト値が設定されたフィールドの意味を区別するかどうかを定義します。

次の順序で生成する

1. リクエストとレスポンスの DTO。
2. 正しい Kotlin の @field: 使用サイトターゲットを使ったバリデーションアノテーション。
3. コントローラーのシグネチャ。
4. サービスインターフェースまたはユースケースの境界。
5. トランスポートモデルとドメインモデル間のマッピングまたは変換コード。
6. @ControllerAdvice またはプロジェクトで相当する仕組みによるエラー処理。
7. コントラクトを実証する、対象を絞った Web レイヤーのテストを1つ。

Kotlin 固有のルール

• コンストラクタープロパティの Jakarta Bean Validation アノテーションには、@field: ターゲットを使用します。
• null 許容フィールドと必須フィールドを明示します。
• 特に PATCH に相当する動作では、null と未指定の違いをコントラクト上の決定事項として扱います。
• Kotlin のコンストラクターのデフォルト値に依存する前に、jackson-module-kotlin または同等のシリアライズサポートを確認します。
• プロジェクトで明確に異なるパターンが使われていない限り、val プロパティを持つ不変 DTO を優先します。

MVC と WebFlux のルール

• リポジトリで意図的に既に混在させている場合を除き、生成する同じエンドポイント内で MVC と WebFlux のスタイルを混在させないでください。
• MVC では、通常の戻り値型とブロッキング方式のサービス境界を優先します。
• コルーチンを使用する WebFlux では、ストリーミングが必要な場合に suspend 関数と Flow<T> を優先します。
• Reactor 方式のコードでは、独自のハイブリッドスタイルを考案せず、プロジェクトで既に使われている Mono と Flux の規約に従います。

高度なコントラクト上の判断

• 人間が読むメッセージが変わっても安定するよう、ペイロードには機械可読なエラーコードを含めることを優先します。
• 400 と 422 のどちらを使うかは慎重に決めます。バリデーションや不正な入力は、ドメインルール違反とは異なります。
• 作成エンドポイントでは、Location を伴う 201 Created がコントラクトに含まれるかを決めます。簡単だからという理由だけで 200 をデフォルトにしないでください。
• 更新エンドポイントでは、同時編集が問題になる場合、バージョンフィールドや ETag、If-Match などの楽観的同時実行制御のシグナルを検討します。
• PATCH のセマンティクスでは、必要に応じて「未指定」「値を指定」「null を指定」の3つの状態を明示的にモデル化します。Kotlin の通常の null 許容フィールドでは、常にこの3つすべてを表現できるとは限りません。
• サービスですでにその方針が標準化されている場合を除き、Page のような Spring 固有のトランスポート型を公開 API のコントラクトとして直接公開することは避けます。
• 日時、列挙型、値クラスのシリアライズを明示します。シリアライザーのデフォルト動作は、バージョンやクライアントによって変わることがよくあります。
• ストリーミングエンドポイントでは、メソッドシグネチャだけでなく、キャンセル、バックプレッシャー、部分書き込み時の動作も検討します。

エキスパートのヒューリスティクス

• コントローラーのコードを書く前に、エラーの契約とバリデーションの契約を設計します。後から追加すると、API に最も大きな変更が生じます。
• トランスポート DTO は範囲を絞り、明示的にします。内部のドメインモデルを再利用すると、最初は時間を節約できますが、その後はずっと余計な時間がかかります。
• サービスが公開されている、または長期にわたって運用される場合は、後方互換性のある契約の進化を優先します。フィールドの追加、安定したコード、計画的な非推奨化を心がけます。
• 可能な場合は、相関 ID の伝播を個々のコントローラーメソッドではなく、フィルターやインターセプターに実装します。

出力の契約

すぐに適用できるパッチ計画、または以下を含む具体的なファイルやコードブロックを返します。

• リクエスト DTO
• レスポンス DTO
• コントローラー
• サービスインターフェースまたはユースケースのエントリーポイント
• 例外マッピングまたはアドバイスの更新
• Web レイヤーのテスト

また、互換性に大きく影響する API 契約上の判断について、簡潔な説明も返します。

ガードレール

• API エラーに内部の例外詳細を漏らさないでください。
• Kotlin で誤ったターゲットにバリデーションアノテーションを使用しないでください。
• 永続化エンティティを公開しないでください。
• 契約を確認せずに、デフォルトの HTTP ステータスコードを前提としないでください。
• モジュールが WebFlux の場合に MVC を選んだり、その逆を行ったりしないでください。

検証チェックリスト

• エンドポイントが、リポジトリで実際に使用されている Spring スタックに対してコンパイルできる。
• 無効な入力に対してバリデーションが実行され、期待される形式のエラーが返る。
• 成功ケースと少なくとも 1 つの失敗ケースが、Web レイヤーのテストでカバーされている。
• シリアライズのルールが、既存のプロジェクト規約に沿っている。

品質基準

このスキルを適切に実行すると、コンパイル、バリデーション、シリアライズが行われ、一貫したエラー処理ができるエンドポイントが得られます。 不適切に実行すると、フレームワークを混在させたり、Kotlin のバリデーションを誤ったり、サービスの他の部分で使われていないエラーモデルを独自に作ったりします。