api-versioning

API のバージョニング（Boot 3／Framework 6）

Boot 3 には、Boot 4 に組み込まれているマッピング用の version 属性はありません。URL セグメント、リクエストヘッダー、メディアタイプのパラメーターのいずれか、明示的な戦略を選び、一貫して適用してください。

可視化され、テスト可能な契約を優先する

公開 API では、通常、/api/v1/orders と /api/v2/orders が最も分かりやすい選択肢です。URL を固定する必要がある場合は、Web 境界でリクエストヘッダーを解決し、バージョンごとのハンドラーにルーティングしてください。バージョンの選択をビジネスサービス内に隠したり、フィルターとコントローラーで重複して実装したりしないでください。

@RestController
@RequestMapping("/api/v1/orders")
class OrderV1Controller {
    @GetMapping("/{id}")
    OrderV1 get(@PathVariable UUID id) { ... }
}

OpenAPI にサポート対象のバージョンを記載し、廃止ポリシーを定義して、サポート対象外のバージョンには一貫したエラーを返してください。バージョンを廃止する際は、レスポンスアドバイスまたはフィルターを通じて Deprecation、Sunset、Link ヘッダーを追加してください。

移行の境界

バージョン固有の DTO とコントローラーは薄く保ってください。両方のバージョンを同じアプリケーションのユースケースにマッピングし、ドメインロジックを各バージョンにコピーしないでください。サポート対象の各バージョンについて契約テストを追加し、メディアタイプを使う場合はコンテンツネゴシエーションを検証してください。

注意点

• エージェントが Boot 3 で Boot 4 の version 属性を使用する — 利用できません。明示的なルーティング戦略を選んでください。
• エージェントが URL、ヘッダー、メディアタイプによる解決を混在させる — 唯一の信頼できる情報源を選んでください。
• エージェントがバージョン分岐をサービスに実装する — 互換性の処理は Web アダプター境界に保ってください。
• エージェントがバージョニングせずにレスポンスフィールドを変更する — 既存の契約を維持するか、新しいバージョンを公開してください。
• エージェントがコントローラーごとに非推奨ヘッダーを作る — アドバイスまたはフィルターに集約してください。
• エージェントが最新バージョンのみを記載する — サポート対象のすべてのバージョンについて、OpenAPI と契約テストを維持してください。