このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring Framework 6.2.11 を使用してください！ |
API のバージョニング
Spring と WebFlux は API のバージョン管理をサポートしています。このセクションでは、サポートの概要と基盤となる戦略について説明します。
以下の関連コンテンツも参照してください:
WebFlux Config で API のバージョン管理を構成する
API バージョンでコントローラーメソッドにアノテーションを付ける地図リクエスト
API バージョンを持つ関数エンドポイントへのルートリクエスト
API バージョン管理のクライアントサポートは、RestClient、WebClient、HTTP サービスクライアントでも利用でき、WebTestClient でのテストにも使用できます。
ApiVersionStrategy
これは API バージョン管理の中心的な戦略であり、バージョン管理に関連するすべての設定を保持します。以下の機能があります。
ApiVersionResolver 経由でリクエストからバージョンを解決します
ApiVersionParser を使用して生のバージョン値を
Comparable<?>に解析します検証リクエストバージョン
ApiVersionStrategy はリクエストを @RequestMapping コントローラーメソッドにマッピングするのに役立ち、WebFlux 設定によって初期化されます。通常、アプリケーションは ApiVersionStrategy と直接やり取りすることはありません。
ApiVersionResolver
この戦略は、リクエストから API バージョンを解決します。WebFlux 設定には、ヘッダー、クエリパラメーター、メディア型パラメーター、URL パスから解決するための組み込みオプションが用意されています。カスタム ApiVersionResolver を使用することもできます。
パスリゾルバーは常に指定されたパスセグメントからバージョンを解決するか、そうでない場合は InvalidApiVersionException を発生させるため、他のリゾルバーに渡すことはできません。 |
ApiVersionParser
この戦略は、生のバージョン値を Comparable<?> に解析できます。これにより、バージョンの比較、ソート、選択が容易になります。デフォルトでは、組み込みの SemanticApiVersionParser がバージョンを major、minor、patWebFluxch 整数値に解析します。マイナー値とパッチ値は、存在しない場合は 0 に設定されます。
検証
リクエストバージョンがサポートされていない場合、InvalidApiVersionException が発生し、400 レスポンスが返されます。デフォルトでは、サポート対象バージョンのリストは、アノテーション付きコントローラーマッピングで宣言されたバージョンから初期化されますが、WebFlux 設定のフラグでこれを無効にし、設定で明示的に指定されたバージョンのみを使用することもできます。
API のバージョン管理が有効になっている場合、デフォルトではバージョンの指定が必須です。指定されていない場合は MissingApiVersionException が発生し、400 レスポンスが返されます。指定を省略可能にすると、最新のバージョンが使用されます。また、使用するデフォルトのバージョンを指定することもできます。
ApiVersionDeprecationHandler
この戦略では、レスポンスヘッダーを介してクライアントに非推奨バージョンに関するヒントや情報を送信するように設定できます。組み込みの StandardApiVersionDeprecationHandler は、RFC 9745 [IETF] (英語) および RFC 8594 [IETF] (英語) で定義されている "Deprecation" "Sunset" ヘッダーと "Link" ヘッダーを設定できます。また、異なるヘッダーごとにカスタムハンドラーを設定することもできます。
リクエストマッピング
ApiVersionStrategy は、リクエストとアノテーション付きコントローラーメソッドのマッピングをサポートします。詳細については、API バージョンを参照してください。
