WebFlux リアクティブスタック

「ノンブロッキング」と「関数型」に触れましたが、リアクティブとはどういう意味でしょうか？

「リアクティブ」という用語は、変化への反応に基づいて構築されたプログラミングモデルを指します。ネットワークコンポーネントは I/O イベントに反応し、UI コントローラーはマウスイベントに反応します。その意味で、ノンブロッキングはリアクティブです。なぜなら、ブロックされる代わりに、操作が完了するかデータが利用可能になると通知に反応するモードになっているからです。

Spring チームが「リアクティブ」に関連付けるもう 1 つの重要なメカニズムは、ノンブロッキングバックプレッシャーです。同期命令型コードでは、呼び出しをブロックすることは、呼び出し側を待機させるバックプレッシャーの自然な形として機能します。ノンブロッキングコードでは、高速プロデューサーがその宛先を圧倒しないように、イベントのレートを制御することが重要になります。

Reactive Streams は、バックプレッシャーのある非同期コンポーネント間の相互作用を定義する小さな仕様 [GitHub] (英語) （Java 9 でも採用 (標準 Javadoc) ）です。たとえば、データリポジトリ（パブリッシャー (英語) として機能）は、HTTP サーバー（サブスクライバー (英語) として機能）がレスポンスに書き込むことができるデータを生成できます。Reactive Streams の主な目的は、サブスクライバーがパブリッシャーがデータを生成する速度と速度を制御できるようにすることです。

Reactive Streams は相互運用性に重要なロールを果たします。ライブラリやインフラストラクチャコンポーネントにとっては興味深いものですが、アプリケーション API としては低レベルすぎるため、あまり有用ではありません。アプリケーションには、Java 8 Stream API に似ていますが、コレクションだけでなく、非同期ロジックを構成するために、より高レベルでより関数的な API が必要です。これがリアクティブライブラリが果たすロールです。

Reactor [GitHub] (英語) は、Spring WebFlux に最適なリアクティブライブラリです。ReactiveX 演算子のボキャブラリー (英語) に合わせた豊富な演算子セットを通じて、0..1（Mono）および 0..N（Flux）のデータシーケンスで動作する Mono (英語) および Flux (英語) API 型を提供します。Reactor は Reactive Streams ライブラリであるため、すべてのオペレーターがノンブロッキングバックプレッシャーをサポートしています。Reactor は、サーバー側の Java に重点を置いています。Spring との緊密なコラボレーションで開発されました。

WebFlux は、コア依存として Reactor を必要としますが、Reactive Streams を介して他のリアクティブライブラリと相互運用できます。一般的なルールとして、WebFlux API は入力としてプレーン Publisher を受け入れ、それを内部で Reactor 型に適合させ、それを使用して、出力として Flux または Mono を返します。任意の Publisher を入力として渡すことができ、出力に操作を適用できますが、別のリアクティブライブラリで使用するために出力を調整する必要があります。可能な場合はいつでも（たとえば、アノテーション付きコントローラー）、WebFlux は RxJava または別のリアクティブライブラリの使用に透過的に適応します。詳細については、リアクティブライブラリを参照してください。

spring-web モジュールには、HTTP 抽象化を含む Spring WebFlux、サポートされるサーバー用の Reactive Streams アダプター、コーデック、およびサーブレット API に匹敵するがノンブロッキング契約を含むコア WebHandler API の基礎となるリアクティブ基盤が含まれています。

その基盤で、Spring WebFlux は 2 つのプログラミングモデルの選択肢を提供します。

Spring MVC または WebFlux ？

当然の質問ですが、あやふやな二分法を設定する質問です。実際には、両方が連携して、使用可能なオプションの範囲を拡張します。この 2 つは、相互に継続性と一貫性を保つように設計されており、並行して使用できます。また、双方からのフィードバックは双方に利益をもたらします。次の図は、この 2 つがどのように関連しているか、共通しているもの、それぞれが一意にサポートするものを示しています。

次の特定の点を考慮することをお勧めします。

Spring WebFlux は、Tomcat、Jetty、Servlet 3.1+ コンテナー、および Netty や Undertow などのサーブレット以外のランタイムでサポートされています。すべてのサーバーは低レベルの共通 API に適合しているため、サーバー間で高レベルのプログラミングモデルをサポートできます。

Spring WebFlux には、サーバーを起動または停止するための組み込みサポートがありません。ただし、Spring 構成と WebFlux インフラストラクチャからアプリケーションをアセンブルし、数行のコードで実行するのは簡単です。

Spring Boot には、これらの手順を自動化する WebFlux スターターがあります。デフォルトでは、スターターは Netty を使用しますが、Maven または Gradle の依存関係を変更することで、Tomcat、Jetty、Undertow に簡単に切り替えることができます。Spring Boot はデフォルトで Netty に設定されています。これは、非同期のノンブロッキングスペースでより広く使用されており、クライアントとサーバーがリソースを共有できるためです。

Tomcat と Jetty は、Spring MVC と WebFlux の両方で使用できます。ただし、使用方法が大きく異なることに注意してください。Spring MVC は、サーブレットブロッキング I/O に依存し、必要に応じてアプリケーションがサーブレット API を直接使用できるようにします。Spring WebFlux は、Servlet 3.1 ノンブロッキング I/O に依存し、低レベルアダプターの背後でサーブレット API を使用します。直接使用するために露出されていません。

Undertow の場合、Spring WebFlux は、サーブレット API なしで Undertow API を直接使用します。

パフォーマンスには多くの特性と意味があります。通常、リアクティブでノンブロッキングでは、アプリケーションの実行速度は向上しません。場合によっては（たとえば、WebClient を使用してリモート呼び出しを並列に実行する場合）全体として、ノンブロッキングの方法を実行するにはより多くの作業が必要であり、必要な処理時間をわずかに増加させる可能性があります。

リアクティブでノンブロッキングの主な期待される利点は、少数の固定スレッドと少ないメモリで拡張できることです。予測可能な方法でスケーリングされるため、負荷がかかった場合でもアプリケーションの回復力が高まります。ただし、これらの利点を観測するには、ある程度の遅延（低速で予測不可能なネットワーク I/O の混在を含む）が必要です。それが、リアクティブスタックの強みを示し始めた場所であり、違いは劇的です。

Spring MVC と Spring WebFlux はどちらもアノテーション付きコントローラーをサポートしていますが、同時実行モデルと、ブロックとスレッドのデフォルトの前提には重要な違いがあります。

Spring MVC (および一般的なサーブレットアプリケーション) では、アプリケーションが現在のスレッドをブロックできることが想定されています (たとえば、リモート呼び出しの場合)。このため、サーブレットコンテナーは大きなスレッドプールを使用して、リクエスト処理中の潜在的なブロックを吸収します。

Spring WebFlux（および一般にノンブロッキングサーバー）では、アプリケーションはブロックされないと想定されています。ノンブロッキングサーバーは、小さな固定サイズのスレッドプール（イベントループワーカー）を使用してリクエストを処理します。

ブロッキングライブラリを使用する必要がある場合はどうなるでしょうか？ Reactor と RxJava は両方とも、異なるスレッドで処理を続行するために publishOn オペレーターを提供します。つまり、簡単な脱出ハッチがあります。ただし、ブロッキング API はこの同時実行モデルには適していません。

Reactor および RxJava では、演算子を使用してロジックを宣言します。実行時に、リアクティブパイプラインが形成され、データが異なるステージで順次処理されます。これの主な利点は、パイプライン内のアプリケーションコードが同時に呼び出されることがないため、アプリケーションが変更可能な状態を保護する必要がないことです。

Spring WebFlux で実行されているサーバーでどのスレッドを表示する必要がありますか？

Spring Framework は、サーバーの起動と停止のサポートを提供しません。サーバーのスレッドモデルを構成するには、サーバー固有の構成 API を使用するか、Spring Boot を使用する場合は、各サーバーの Spring Boot 構成オプションを確認する必要があります。WebClient を直接構成できます。他のすべてのライブラリについては、それぞれのドキュメントを参照してください。

HttpHandler (Javadoc) は、リクエストとレスポンスを処理する単一のメソッドを持つ単純な契約です。これは意図的に最小限に抑えられており、その主な唯一の目的は、さまざまな HTTP サーバー API を最小限に抽象化することです。

次の表に、サポートされているサーバー API を示します。

次の表に、サーバーの依存関係を示します（サポートされるバージョン [GitHub] (英語) も参照）。

以下のコードスニペットは、各サーバー API で HttpHandler アダプターを使用することを示しています。

Reactor Netty

Undertow

Tomcat

Jetty

Servlet 3.1+ コンテナー

Servlet 3.1+ コンテナーに WAR としてデプロイするには、AbstractReactiveWebInitializer (Javadoc) を継承して WAR に含めることができます。そのクラスは、HttpHandler を ServletHttpHandlerAdapter でラップし、それを Servlet として登録します。

org.springframework.web.server パッケージは HttpHandler 契約に基づいており、複数の WebExceptionHandler (Javadoc) 、複数の WebFilter (Javadoc) 、単一の WebHandler (Javadoc) コンポーネントのチェーンを介してリクエストを処理するための汎用 Web API を提供します。チェーンは、コンポーネントが自動検出される Spring ApplicationContext を指すか、コンポーネントをビルダーに登録するだけで、WebHttpHandlerBuilder と組み合わせることができます。

HttpHandler には、さまざまな HTTP サーバーの使用を抽象化するという単純なゴールがありますが、WebHandler API は、次のような Web アプリケーションで一般的に使用される広範な機能セットを提供することを目的としています。

Web MVC

WebHandler API では、WebFilter を使用して、フィルターの残りの処理チェーンおよびターゲット WebHandler の前後にインターセプションスタイルのロジックを適用できます。WebFlux 構成を使用する場合、WebFilter の登録は、Spring Bean として宣言し、（オプションで）Bean 宣言で @Order を使用するか、Ordered を実装することによって優先順位を表すのと同じくらい簡単です。

Web MVC

WebHandler API では、WebExceptionHandler を使用して、WebFilter インスタンスのチェーンおよびターゲット WebHandler からの例外を処理できます。WebFlux 構成を使用する場合、WebExceptionHandler の登録は、Spring Bean として宣言し、（オプションで）Bean 宣言で @Order を使用するか、Ordered を実装することによって優先順位を表すのと同じくらい簡単です。

次の表は、利用可能な WebExceptionHandler 実装を説明しています。

Web MVC

spring-web および spring-core モジュールは、Reactive Streams バックプレッシャーを使用したノンブロッキング I/O を介して、上位レベルのオブジェクトとの間でバイトコンテンツを直列化および逆直列化するサポートを提供します。このサポートについて以下に説明します。

spring-core モジュールは、byte[]、ByteBuffer、DataBuffer、Resource、String エンコーダーおよびデコーダーの実装を提供します。spring-web モジュールは、Jackson JSON、Jackson Smile、JAXB2、Protocol Buffers、その他のエンコーダーとデコーダー、フォームデータ、マルチパートコンテンツ、サーバー送信イベントなどの Web のみの HTTP メッセージリーダーとライターの実装を提供します。

ClientCodecConfigurer および ServerCodecConfigurer は、通常、アプリケーションで使用するコーデックを構成およびカスタマイズするために使用されます。HTTP メッセージコーデックの構成に関するセクションを参照してください。

Web MVC

Spring での DEBUG レベルのロギング WebFlux は、コンパクト、最小限、人に優しいように設計されています。これは、特定の課題をデバッグする場合にのみ役立つ他の情報と比較して、何度も役立つ情報の価値の高いビットに焦点を当てています。

TRACE レベルのログは、一般に DEBUG と同じ原則に従います（たとえば、ファイアホースであってはなりません）。ただし、課題のデバッグに使用できます。さらに、一部のログメッセージでは、TRACE と DEBUG で詳細レベルが異なる場合があります。

適切なログは、ログを使用した経験から得られます。記載されているゴールを達成できないものを見つけた場合は、お知らせください。

Web MVC

DispatcherHandler は、リクエストを処理して適切なレスポンスをレンダリングするために特別な Bean に委譲します。「特別な Bean」とは、WebFlux フレームワーク契約を実装する Spring 管理の Object インスタンスを意味します。通常、これらにはビルトイン契約が付属していますが、プロパティをカスタマイズしたり、拡張したり、置き換えたりすることができます。

次の表に、DispatcherHandler によって検出された特別な Bean を示します。下位レベルで検出された他の Bean もいくつかあることに注意してください（Web ハンドラー API の特別な Bean 型を参照）。

Web MVC

アプリケーションは、リクエストの処理に必要なインフラストラクチャ Bean（Web ハンドラー API および DispatcherHandler にリストされている）を宣言できます。ただし、ほとんどの場合、WebFlux 構成が最適な出発点です。必要な Bean を宣言し、それをカスタマイズするための高レベルの構成コールバック API を提供します。

Web MVC

DispatcherHandler は、リクエストを次のように処理します。

HandlerAdapter を介したハンドラーの呼び出しからの戻り値は、追加のコンテキストとともに HandlerResult としてラップされ、そのサポートを要求する最初の HandlerResultHandler に渡されます。次の表に、利用可能な HandlerResultHandler 実装を示します。これらはすべて WebFlux 構成で宣言されています。

Web MVC

HandlerAdapter から返された HandlerResult は、ハンドラー固有のメカニズムに基づいてエラー処理用の関数を公開できます。このエラー関数は次の場合に呼び出されます:

エラー関数は、ハンドラーから返されるリアクティブ型がデータ項目を生成する前にエラーシグナルが発生する限り、レスポンスを（たとえば、エラー状況に）変更できます。

これが、@Controller クラスの @ExceptionHandler メソッドがサポートされる方法です。対照的に、Spring MVC での同じサポートは HandlerExceptionResolver 上に構築されています。通常、これは重要ではありません。ただし、WebFlux では、ハンドラーが選択される前に発生した例外を @ControllerAdvice を使用して処理できないことに注意してください。

「アノテーション付きコントローラー」セクションの例外の管理または WebHandler API セクションの例外も参照してください。

Web MVC

ビューリゾルバーにより、特定のビューテクノロジに縛られることなく、HTML テンプレートとモデルを使用してブラウザーにレンダリングできます。Spring WebFlux では、ViewResolver インスタンスを使用してストリング（論理ビュー名を表す）を View インスタンスにマップする専用 HandlerResultHandler を介して、ビューリゾルバーがサポートされています。次に、View を使用してレスポンスをレンダリングします。

Web MVC

標準の Spring Bean 定義を使用して、コントローラー Bean を定義できます。@Controller ステレオタイプは自動検出を可能にし、クラスパス内の @Component クラスを検出し、それらの Bean 定義を自動登録するための Spring 一般サポートと連携しています。また、アノテーション付きクラスのステレオタイプとしても機能し、Web コンポーネントとしてのロールを示します。

そのような @Controller Bean の自動検出を有効にするには、次の例に示すように、Java 構成にコンポーネントスキャンを追加できます。

@RestController は、それ自体が @Controller および @ResponseBody でメタアノテーションが付けられた合成アノテーションであり、すべてのメソッドが型レベルの @ResponseBody アノテーションを継承するコントローラーを示します。ビューリゾルバーと HTML テンプレートを使用したレンダリングではなく、レスポンス本文に直接書き込みます。

Web MVC

@RequestMapping アノテーションは、リクエストをコントローラーメソッドにマップするために使用されます。URL、HTTP メソッド、リクエストパラメーター、ヘッダー、メディア型で一致するさまざまな属性があります。クラスレベルで使用して共有マッピングを表現したり、メソッドレベルで使用して特定のエンドポイントマッピングに絞り込んだりできます。

@RequestMapping の HTTP メソッド固有のショートカットバリアントもあります。

ほとんどのコントローラーメソッドは、デフォルトですべての HTTP メソッドに一致する @RequestMapping を使用するのではなく、特定の HTTP メソッドにマップされる必要があるため、上記のアノテーションはカスタムアノテーションです。同時に、共有マッピングを表現するには、クラスレベルで @RequestMapping が必要です。

次の例では、型およびメソッドレベルのマッピングを使用しています。

Web MVC

@RequestMapping ハンドラーメソッドには柔軟なシグネチャーがあり、サポートされているコントローラーメソッドの引数と戻り値の範囲から選択できます。

Web MVC

You can use the @ModelAttribute annotation:

This section discusses @ModelAttribute methods, or the second item from the preceding list. A controller can have any number of @ModelAttribute methods. All such methods are invoked before @RequestMapping methods in the same controller. A @ModelAttribute method can also be shared across controllers through @ControllerAdvice. See the section on Controller Advice for more details.

@ModelAttribute methods have flexible method signatures. They support many of the same arguments as @RequestMapping methods (except for @ModelAttribute itself and anything related to the request body).

The following example uses a @ModelAttribute method:

The following example adds one attribute only:

Spring WebFlux, unlike Spring MVC, explicitly supports reactive types in the model (for example, Mono<Account> or io.reactivex.Single<Account>). Such asynchronous model attributes can be transparently resolved (and the model updated) to their actual values at the time of @RequestMapping invocation, provided a @ModelAttribute argument is declared without a wrapper, as the following example shows:

In addition, any model attributes that have a reactive type wrapper are resolved to their actual values (and the model updated) just prior to view rendering.

You can also use @ModelAttribute as a method-level annotation on @RequestMapping methods, in which case the return value of the @RequestMapping method is interpreted as a model attribute. This is typically not required, as it is the default behavior in HTML controllers, unless the return value is a String that would otherwise be interpreted as a view name. @ModelAttribute can also help to customize the model attribute name, as the following example shows:

Web MVC

@Controller or @ControllerAdvice classes can have @InitBinder methods, to initialize instances of WebDataBinder. Those, in turn, are used to:

@InitBinder methods can register controller-specific java.beans.PropertyEditor or Spring Converter and Formatter components. In addition, you can use the WebFlux Java configuration to register Converter and Formatter types in a globally shared FormattingConversionService.

@InitBinder methods support many of the same arguments that @RequestMapping methods do, except for @ModelAttribute (command object) arguments. Typically, they are declared with a WebDataBinder argument, for registrations, and a void return value. The following example uses the @InitBinder annotation:

Alternatively, when using a Formatter-based setup through a shared FormattingConversionService, you could re-use the same approach and register controller-specific Formatter instances, as the following example shows:

Web MVC

@Controller and @ControllerAdvice classes can have @ExceptionHandler methods to handle exceptions from controller methods. The following example includes such a handler method:

The exception can match against a top-level exception being propagated (that is, a direct IOException being thrown) or against the immediate cause within a top-level wrapper exception (for example, an IOException wrapped inside an IllegalStateException).

For matching exception types, preferably declare the target exception as a method argument, as shown in the preceding example. Alternatively, the annotation declaration can narrow the exception types to match. We generally recommend being as specific as possible in the argument signature and to declare your primary root exception mappings on a @ControllerAdvice prioritized with a corresponding order. See the MVC section for details.

Support for @ExceptionHandler methods in Spring WebFlux is provided by the HandlerAdapter for @RequestMapping methods. See DispatcherHandler for more detail.

Web MVC

Typically, the @ExceptionHandler, @InitBinder, and @ModelAttribute methods apply within the @Controller class (or class hierarchy) in which they are declared. If you want such methods to apply more globally (across controllers), you can declare them in a class annotated with @ControllerAdvice or @RestControllerAdvice.

@ControllerAdvice is annotated with @Component, which means that such classes can be registered as Spring beans through component scanning. @RestControllerAdvice is a composed annotation that is annotated with both @ControllerAdvice and @ResponseBody, which essentially means @ExceptionHandler methods are rendered to the response body through message conversion (versus view resolution or template rendering).

On startup, the infrastructure classes for @RequestMapping and @ExceptionHandler methods detect Spring beans annotated with @ControllerAdvice and then apply their methods at runtime. Global @ExceptionHandler methods (from a @ControllerAdvice) are applied after local ones (from the @Controller). By contrast, global @ModelAttribute and @InitBinder methods are applied before local ones.

By default, @ControllerAdvice methods apply to every request (that is, all controllers), but you can narrow that down to a subset of controllers by using attributes on the annotation, as the following example shows:

The selectors in the preceding example are evaluated at runtime and may negatively impact performance if used extensively. See the @ControllerAdvice (Javadoc) javadoc for more details.

Web MVC

In WebFlux.fn, an HTTP request is handled with a HandlerFunction: a function that takes ServerRequest and returns a delayed ServerResponse (i.e. Mono<ServerResponse>). Both the request and the response object have immutable contracts that offer JDK 8-friendly access to the HTTP request and response. HandlerFunction is the equivalent of the body of a @RequestMapping method in the annotation-based programming model.

Incoming requests are routed to a handler function with a RouterFunction: a function that takes ServerRequest and returns a delayed HandlerFunction (i.e. Mono<HandlerFunction>). When the router function matches, a handler function is returned; otherwise an empty Mono. RouterFunction is the equivalent of a @RequestMapping annotation, but with the major difference that router functions provide not just data, but also behavior.

RouterFunctions.route() provides a router builder that facilitates the creation of routers, as the following example shows:

One way to run a RouterFunction is to turn it into an HttpHandler and install it through one of the built-in server adapters:

ほとんどのアプリケーションは、WebFlux Java 構成を介して実行できます。サーバーの実行を参照してください。

Web MVC

ServerRequest および ServerResponse は、HTTP リクエストおよびレスポンスへの JDK 8 フレンドリーなアクセスを提供する不変のインターフェースです。リクエストとレスポンスの両方が、ボディストリームに対する Reactive Streams (英語) バックプレッシャーを提供します。リクエスト本体は、Reactor Flux または Mono で表されます。レスポンス本体は、Flux および Mono を含む Reactive Streams Publisher で表されます。詳細については、リアクティブライブラリを参照してください。

Web MVC

ルーター関数を使用して、リクエストを対応する HandlerFunction にルーティングします。通常、ルーター関数は自分で作成するのではなく、RouterFunctions ユーティリティクラスのメソッドを使用して作成します。RouterFunctions.route() （パラメーターなし）は、ルーター関数を作成するための流れるようなビルダーを提供しますが、RouterFunctions.route(RequestPredicate, HandlerFunction) はルーターを直接作成する方法を提供します。

通常、route() ビルダーを使用することをお勧めします。これは、検出が困難な静的インポートを必要とせずに、一般的なマッピングシナリオに便利なショートカットを提供するためです。たとえば、ルーター関数ビルダーは、GET リクエストのマッピングを作成するメソッド GET(String, HandlerFunction) を提供します。POST 用の POST(String, HandlerFunction)。

HTTP メソッドベースのマッピングに加えて、ルートビルダーは、リクエストにマッピングするときに追加の述語を導入する方法を提供します。HTTP メソッドごとに、RequestPredicate をパラメーターとして受け取るオーバーロードされたバリアントがありますが、追加の制約を表現できます。

Web MVC

HTTP サーバーでルーター関数をどのように実行しますか？ 簡単なオプションは、次のいずれかを使用して、ルーター関数を HttpHandler に変換することです。

その後、サーバー固有の手順について HttpHandler に従うことにより、返された HttpHandler を多数のサーバーアダプターで使用できます。

Spring Boot でも使用されるより一般的なオプションは、WebFlux 構成を介して DispatcherHandler ベースのセットアップで実行することです。WebFlux 構成は、Spring 構成を使用して、リクエストの処理に必要なコンポーネントを宣言します。WebFlux Java 構成は、関数エンドポイントをサポートするために次のインフラストラクチャコンポーネントを宣言します。

上記のコンポーネントにより、関数エンドポイントは DispatcherHandler リクエスト処理ライフサイクルに適合し、アノテーション付きコントローラー（存在する場合）と並行して（潜在的に）実行されます。また、Spring Boot WebFlux スターターが関数エンドポイントを有効にする方法でもあります。

次の例は、WebFlux Java 構成を示しています（実行方法については、DispatcherHandler を参照してください）。

Web MVC

ルーティング関数ビルダーで before、after、filter メソッドを使用して、ハンドラー関数をフィルター処理できます。アノテーションを使用すると、@ControllerAdvice、ServletFilter、その両方を使用して同様の機能を実現できます。フィルターは、ビルダーによって作成されたすべてのルートに適用されます。これは、ネストされたルートで定義されたフィルターが「トップレベル」ルートに適用されないことを意味します。たとえば、次の例について考えてみます。

ルータービルダーの filter メソッドは HandlerFilterFunction を取ります。これは、ServerRequest と HandlerFunction を取り、ServerResponse を返す関数です。ハンドラー関数パラメーターは、チェーンの次の要素を表します。これは通常、ルーティング先のハンドラーですが、複数が適用される場合は別のフィルターにすることもできます。

特定のパスが許可されているかどうかを判断できる SecurityManager があると仮定して、ルートに簡単なセキュリティフィルターを追加できます。次の例は、その方法を示しています。

上記の例は、next.handle(ServerRequest) の呼び出しがオプションであることを示しています。アクセスが許可されている場合にのみハンドラー関数を実行させます。

ルーター関数ビルダーで filter メソッドを使用する以外に、RouterFunction.filter(HandlerFilterFunction) を介して既存のルーター関数にフィルターを適用することができます。

Spring MVC および Spring WebFlux

UriComponentsBuilder は、次の例に示すように、変数を持つ URI テンプレートから URI を作成できます。

前述の例は、次の例に示すように、1 つのチェーンに統合し、buildAndExpand で短縮できます。

次の例に示すように、URI に直接移動することで（エンコードを暗示する）、さらに短くすることができます。

次の例に示すように、完全な URI テンプレートを使用してさらに短縮できます。

Spring MVC および Spring WebFlux

UriComponentsBuilder は UriBuilder を実装しています。UriBuilderFactory を使用して、UriBuilder を作成できます。UriBuilderFactory と UriBuilder は、ベース URL、エンコード設定、その他の詳細などの共有構成に基づいて、URI テンプレートから URI を構築するプラグ可能なメカニズムを提供します。

RestTemplate および WebClient を UriBuilderFactory で構成して、URI の準備をカスタマイズできます。DefaultUriBuilderFactory は、UriComponentsBuilder を内部で使用し、共有構成オプションを公開する UriBuilderFactory のデフォルト実装です。

次の例は、RestTemplate を構成する方法を示しています。

次の例では、WebClient を構成します。

さらに、DefaultUriBuilderFactory を直接使用することもできます。UriComponentsBuilder の使用に似ていますが、次の例に示すように、静的ファクトリメソッドの代わりに、構成と設定を保持する実際のインスタンスです。

Spring MVC および Spring WebFlux

UriComponentsBuilder は、2 つのレベルでエンコードオプションを公開します。

どちらのオプションも、非 ASCII 文字と不正な文字をエスケープされたオクテットに置き換えます。ただし、最初のオプションは、URI 変数に表示される予約された意味で文字を置き換えます。

ほとんどの場合、最初のオプションは URI 変数を完全にエンコードされる不透明（OPAQUE）データとして扱うため、期待どおりの結果が得られる可能性があります。2 番目のオプションは、URI 変数に意図的に予約文字が含まれている場合に役立ちます。2 番目のオプションは、URI 変数をまったく展開しない場合にも役立ちます。これは、偶然に URI 変数のように見えるものもエンコードするためです。

次の例では、最初のオプションを使用しています。

次の例に示すように、URI に直接移動することで、前述の例を短縮できます（エンコードを意味します）。

次の例に示すように、完全な URI テンプレートを使用してさらに短縮できます。

WebClient と RestTemplate は、UriBuilderFactory 戦略を通じて内部で URI テンプレートを拡張およびエンコードします。次の例に示すように、どちらもカスタム戦略で構成できます。

DefaultUriBuilderFactory 実装は、UriComponentsBuilder を内部的に使用して URI テンプレートを展開およびエンコードします。ファクトリとして、以下のエンコードモードのいずれかに基づいて、エンコードへのアプローチを構成する単一の場所を提供します。

RestTemplate は、歴史的な理由と後方互換性のために EncodingMode.URI_COMPONENT に設定されています。WebClient は、DefaultUriBuilderFactory のデフォルト値に依存しています。これは、5.0.x の EncodingMode.URI_COMPONENT から 5.1 の EncodingMode.TEMPLATE_AND_VALUES に変更されました。

Web MVC

セキュリティ上の理由から、ブラウザーは現在のオリジンの外部のリソースへの AJAX 呼び出しを禁止しています。例: 銀行口座を 1 つのタブに、evil.com を別のタブに持つことができます。evil.com のスクリプトは、アカウントからお金を引き出すなど、認証情報を使用して銀行の API に AJAX リクエストを行うことはできません！

Cross-Origin Resource Sharing（CORS）は、ほとんどのブラウザー (英語) で実装されている W3C 仕様 (英語) であり、IFRAME または JSONP に基づく安全性が低く、強力ではない回避策を使用するのではなく、認可される種類のクロスドメインリクエストを指定できます。

Web MVC

CORS 仕様は、プリフライト、シンプル、実際のリクエストを区別します。CORS がどのように機能するかを学ぶために、他の多くの人と一緒にこの記事 [Mozilla] を読むか、詳細について仕様を参照してください。

Spring WebFlux HandlerMapping 実装は、CORS の組み込みサポートを提供します。リクエストをハンドラーに正常にマッピングした後、HandlerMapping は指定されたリクエストとハンドラーの CORS 設定をチェックし、さらにアクションを実行します。プリフライトリクエストは直接処理されますが、シンプルで実際の CORS リクエストはインターセプトされ、検証され、必要な CORS レスポンスヘッダーが設定されます。

クロスオリジンリクエストを有効にするには（つまり、Origin ヘッダーが存在し、リクエストのホストとは異なる）、明示的に宣言された CORS 構成が必要です。一致する CORS 設定が見つからない場合、プリフライトリクエストは拒否されます。CORS ヘッダーは単純および実際の CORS リクエストのレスポンスに追加されないため、ブラウザーはそれらを拒否します。

各 HandlerMapping は、URL パターンベースの CorsConfiguration マッピングで個別に構成 (Javadoc) できます。ほとんどの場合、アプリケーションは WebFlux Java 構成を使用してこのようなマッピングを宣言します。これにより、単一のグローバルマップがすべての HandlerMapping 実装に渡されます。

HandlerMapping レベルのグローバル CORS 構成と、よりきめ細かいハンドラーレベルの CORS 構成を組み合わせることができます。例: アノテーション付きコントローラーは、クラスまたはメソッドレベルの @CrossOrigin アノテーションを使用できます（他のハンドラーは CorsConfigurationSource を実装できます）。

グローバル設定とローカル設定を結合するためのルールは、一般的に付加的です。たとえば、すべてのグローバルおよびすべてのローカルオリジン。allowCredentials や maxAge など、単一の値しか受け入れられない属性の場合、ローカルはグローバル値をオーバーライドします。詳細については、CorsConfiguration#combine(CorsConfiguration) (Javadoc) を参照してください。

Web MVC

認証情報付きリクエストで CORS を使用するには、allowedCredentials を有効にする必要があります。このオプションでは、構成されたドメインとの高レベルの信頼が確立され、Cookie や CSRF トークンなどのユーザー固有の機密情報が公開されるため、Web アプリケーションの攻撃対象領域が増えることに注意してください。

資格情報を有効にすると、構成された "*" CORS ワイルドカードの処理方法にも影響します。

Web MVC

@CrossOrigin (Javadoc) アノテーションは、次の例に示すように、アノテーション付きコントローラーメソッドでクロスオリジンリクエストを有効にします。

デフォルトでは、@CrossOrigin は次を許可します。

allowCredentials はデフォルトでは有効になっていません。これは、ユーザー固有の機密情報（Cookie や CSRF トークンなど）を公開する信頼レベルを確立し、適切な場合にのみ使用する必要があるためです。有効になっている場合は、allowOrigins を 1 つ以上の特定のドメインに設定する必要があります（ただし、特別な値 "*" は設定しないでください）。または、allowOriginPatterns プロパティを使用して動的な起点のセットに一致させることもできます。

maxAge は 30 分に設定されています。

@CrossOrigin はクラスレベルでもサポートされ、すべてのメソッドに継承されます。次の例では、特定のドメインを指定し、maxAge を 1 時間に設定します。

次の例に示すように、@CrossOrigin はクラスレベルとメソッドレベルの両方で使用できます。

Web MVC

細分化されたコントローラーメソッドレベルの構成に加えて、おそらくグローバルな CORS 構成も定義する必要があります。URL ベースの CorsConfiguration マッピングは、HandlerMapping で個別に設定できます。ただし、ほとんどのアプリケーションは、WebFlux Java 構成を使用してこれを実行します。

デフォルトでは、グローバル構成により以下が有効になります。

allowedCredentials はデフォルトでは有効になっていません。これは、ユーザー固有の機密情報（Cookie や CSRF トークンなど）を公開する信頼レベルを確立し、適切な場合にのみ使用する必要があるためです。有効になっている場合は、allowOrigins を 1 つ以上の特定のドメインに設定する必要があります（ただし、特別な値 "*" は設定しないでください）。または、allowOriginPatterns プロパティを使用して動的な起点のセットに一致させることもできます。

maxAge は 30 分に設定されています。

WebFlux Java 構成で CORS を有効にするには、次の例に示すように、CorsRegistry コールバックを使用できます。

Web MVC

組み込みの CorsWebFilter (Javadoc) を使用して CORS サポートを適用できます。これは、関数エンドポイントに適しています。

フィルターを構成するには、次の例に示すように、CorsWebFilter Bean を宣言し、CorsConfigurationSource をコンストラクターに渡すことができます。

Web MVC

Thymeleaf は、ダブルクリックでブラウザーでプレビューできる自然な HTML テンプレートを強調する最新のサーバー側 Java テンプレートエンジンです。これは、UI テンプレート（デザイナーなど）での独立した作業に必要なく、非常に役立ちます。実行中のサーバー。Thymeleaf は広範な機能セットを提供し、積極的に開発および保守されています。より完全な導入については、Thymeleaf (英語) プロジェクトのホームページを参照してください。

Thymeleaf と Spring の統合 WebFlux は、Thymeleaf プロジェクトによって管理されます。構成には、SpringResourceTemplateResolver、SpringWebFluxTemplateEngine、ThymeleafReactiveViewResolver などのいくつかの Bean 宣言が含まれます。詳細については、Thymeleaf+Spring (英語) および WebFlux 統合の発表 (英語) を参照してください。

Web MVC

Apache FreeMarker (英語) は、HTML からメールなどへのあらゆる種類のテキスト出力を生成するためのテンプレートエンジンです。Spring Framework には、Spring WebFlux と FreeMarker テンプレートを使用するための組み込みの統合機能があります。

Web MVC

Spring Framework には、JSR-223 (英語) Java スクリプトエンジン上で実行できるテンプレートライブラリで Spring WebFlux を使用するための組み込みの統合があります。次の表は、さまざまなスクリプトエンジンでテストしたテンプレートライブラリを示しています。

Web MVC

コンテンツネゴシエーションの目的では、クライアントからリクエストされたコンテンツ型に応じて、HTML テンプレートを使用したモデルのレンダリングと他の形式（JSON や XML など）としてのレンダリングを切り替えることができると便利です。そうすることをサポートするために、Spring WebFlux は HttpMessageWriterView を提供します。これを使用して、Jackson2JsonEncoder、Jackson2SmileEncoder、Jaxb2XmlEncoder などの spring-web から利用可能なコーデックのいずれかをプラグインできます。

他のビューテクノロジーとは異なり、HttpMessageWriterView は ViewResolver を必要とせず、代わりにデフォルトビューとして設定されます。異なる HttpMessageWriter インスタンスまたは Encoder インスタンスをラップして、このようなデフォルトビューを 1 つ以上構成できます。リクエストされたコンテンツ型に一致するものが実行時に使用されます。

ほとんどの場合、モデルには複数の属性が含まれます。どれを直列化するかを決定するために、レンダリングに使用するモデル属性の名前で HttpMessageWriterView を構成できます。モデルに含まれる属性が 1 つだけの場合、その属性が使用されます。

Web MVC

CacheControl (Javadoc) は、Cache-Control ヘッダーに関連する設定の構成をサポートし、多くの場所で引数として受け入れられます。

RFC 7234 [IETF] (英語) は Cache-Control レスポンスヘッダーのすべての可能なディレクティブを記述しますが、CacheControl 型は、次の例に示すように、一般的なシナリオに焦点を当てたユースケース指向のアプローチを取ります。

Web MVC

コントローラーは、HTTP キャッシングの明示的なサポートを追加できます。リソースの lastModified または ETag 値は、条件付きリクエストヘッダーと比較する前に計算する必要があるため、そうすることをお勧めします。次の例に示すように、コントローラーは ETag および Cache-Control 設定を ResponseEntity に追加できます。

前述の例では、条件付きリクエストヘッダーとの比較でコンテンツが変更されていないことが示された場合、空のボディを含む 304（NOT_MODIFIED）レスポンスが送信されます。それ以外の場合、ETag および Cache-Control ヘッダーがレスポンスに追加されます。

次の例に示すように、コントローラーの条件付きリクエストヘッダーに対してチェックを行うこともできます。

条件付きリクエストを eTag 値、lastModified 値、その両方に対してチェックするための 3 つのバリアントがあります。条件付き GET および HEAD リクエストの場合、レスポンスを 304（NOT_MODIFIED）に設定できます。条件付き POST、PUT、DELETE の場合、代わりにレスポンスを 412（PRECONDITION_FAILED）に設定して、同時変更を防ぐことができます。

Web MVC

最適なパフォーマンスを得るには、Cache-Control と条件付きレスポンスヘッダーで静的リソースを提供する必要があります。静的リソースの構成に関するセクションを参照してください。

Web MVC

次の例に示すように、Java config で @EnableWebFlux アノテーションを使用できます。

上記の例では、多数の Spring WebFlux インフラストラクチャ Bean を登録し、JSON、XML などのクラスパスで利用可能な依存関係に適応しています。

Web MVC

Java 構成では、次の例に示すように、WebFluxConfigurer インターフェースを実装できます。

Web MVC

デフォルトでは、さまざまな数値および日付型のフォーマッタがインストールされ、フィールドでの @NumberFormat および @DateTimeFormat によるカスタマイズのサポートがインストールされています。

Java config でカスタムフォーマッタとコンバーターを登録するには、次を使用します。

デフォルトでは、Spring WebFlux は、日付値を解析およびフォーマットするときに、リクエストロケールを考慮します。これは、日付が「入力」フォームフィールドを持つ文字列として表されるフォームで機能します。ただし、「日付」および「時刻」フォームフィールドの場合、ブラウザーは HTML 仕様で定義されている固定形式を使用します。このような場合、日付と時刻のフォーマットは次のようにカスタマイズできます。

Web MVC

デフォルトでは、Bean バリデーションがクラスパスに存在する場合（たとえば、Hibernate バリデーター）、LocalValidatorFactoryBean は、@Controller メソッド引数の @Valid および @Validated で使用するためのグローバルバリデーターとして登録されます。

Java 構成では、次の例に示すように、グローバル Validator インスタンスをカスタマイズできます。

次の例に示すように、Validator 実装をローカルに登録することもできます。

Web MVC

Spring WebFlux が、リクエストから @Controller インスタンスのリクエストされたメディア型を決定する方法を設定できます。デフォルトでは、Accept ヘッダーのみがチェックされますが、クエリパラメーターベースの戦略を有効にすることもできます。

次の例は、リクエストされたコンテンツ型の解決をカスタマイズする方法を示しています。

Web MVC

次の例は、リクエストとレスポンスの本文の読み取りおよび書き込み方法をカスタマイズする方法を示しています。

ServerCodecConfigurer は、デフォルトのリーダーとライターのセットを提供します。これを使用して、リーダーとライターを追加したり、デフォルトのものをカスタマイズしたり、デフォルトのものを完全に置き換えたりできます。

Jackson JSON および XML の場合、Jackson2ObjectMapperBuilder (Javadoc) の使用を検討してください。Jackson2ObjectMapperBuilder (Javadoc) は、Jackson のデフォルトプロパティを次のようにカスタマイズします。

また、次の既知のモジュールがクラスパスで検出された場合、自動的に登録します。

Web MVC

次の例は、ビューリゾルバーを構成する方法を示しています。

ViewResolverRegistry には、Spring Framework が統合するビューテクノロジーへのショートカットがあります。次の例では、FreeMarker を使用しています（これには、基になる FreeMarker ビューテクノロジの構成も必要です）

次の例に示すように、ViewResolver 実装をプラグインすることもできます。

コンテンツネゴシエーションをサポートし、ビューリゾルバー (HTML 以外) を介して他の形式をレンダリングするには、spring-web から利用可能なコーデックのいずれかを受け入れる HttpMessageWriterView 実装に基づいて、1 つまたは複数の既定のビューを構成できます。次の例は、その方法を示しています。

Spring WebFlux と統合されているビューテクノロジーの詳細については、ビューテクノロジーを参照してください。

Web MVC

このオプションは、Resource (Javadoc) ベースの場所のリストから静的リソースを提供する便利な方法を提供します。

次の例では、/resources で始まるリクエストを指定すると、相対パスを使用して、クラスパス上の /static に関連する静的リソースを見つけて提供します。ブラウザーのキャッシュを最大限に活用し、ブラウザーによる HTTP リクエストを削減するために、リソースには 1 年間の有効期限が設定されています。Last-Modified ヘッダーも評価され、存在する場合は 304 ステータスコードが返されます。次のリストは、例を示しています。

静的リソースの HTTP キャッシュサポートも参照してください。

リソースハンドラーは、ResourceResolver (Javadoc) 実装と ResourceTransformer (Javadoc) 実装のチェーンもサポートしています。これらを使用して、最適化されたリソースを操作するためのツールチェーンを作成できます。

コンテンツ、固定アプリケーションバージョン、その他の情報から計算された MD5 ハッシュに基づいて、バージョン管理されたリソース URL に VersionResourceResolver を使用できます。ContentVersionStrategy （MD5 ハッシュ）は、いくつかの注目すべき例外（モジュールローダーで使用される JavaScript リソースなど）がある場合に適しています。

次の例は、Java 構成で VersionResourceResolver を使用する方法を示しています。

ResourceUrlProvider を使用して URL を書き換え、リゾルバーとトランスフォーマーの完全なチェーンを適用できます（たとえば、バージョンを挿入するため）。WebFlux 構成は、ResourceUrlProvider を提供するため、他に注入することができます。

Spring MVC とは異なり、現時点では、WebFlux には静的リソース URL を透過的に書き換える方法がありません。これは、リゾルバーとトランスフォーマーの非ブロックチェーンを利用できるビューテクノロジーがないためです。ローカルリソースのみを提供する場合の回避策は、ResourceUrlProvider を直接 (たとえば、カスタム要素を介して) 使用してブロックすることです。

EncodedResourceResolver （たとえば、Gzip、Brotli エンコード）と VersionedResourceResolver の両方を使用する場合、エンコードされていないファイルに基づいてコンテンツベースのバージョンが常に確実に計算されるように、この順序で登録する必要があります。

WebJars (英語) の場合、/webjars/jquery/1.2.0/jquery.min.js のようなバージョン管理された URL が推奨され、最も効率的な使用方法です。関連するリソースの場所は Spring Boot を使用してすぐに構成でき (または ResourceHandlerRegistry を介して手動で構成できます)、org.webjars:webjars-locator-core 依存関係を追加する必要はありません。

/webjars/jquery/jquery.min.js のようなバージョンのない URL は、org.webjars:webjars-locator-core ライブラリがクラスパスに存在する場合に自動的に登録される WebJarsResourceResolver を介してサポートされますが、アプリケーションの起動を遅くする可能性のあるクラスパススキャンが犠牲になります。リゾルバーは、jar のバージョンを含むように URL を書き換えることができます。また、バージョンのない受信 URL (たとえば、/webjars/jquery/jquery.min.js から /webjars/jquery/1.2.0/jquery.min.js へ) と照合することもできます。

Web MVC

パスマッチングに関連するオプションをカスタマイズできます。個々のオプションの詳細については、PathMatchConfigurer javadoc を参照してください。次の例は、PathMatchConfigurer の使用方法を示しています。

WebFlux Java 構成は、WebSocket ハンドラーの呼び出しのサポートを提供する WebSocketHandlerAdapter Bean を宣言します。つまり、WebSocket ハンドシェイクリクエストを処理するために必要なことは、WebSocketHandler を SimpleUrlHandlerMapping を介して URL にマップすることだけです。

場合によっては、WebSocket サーバーのプロパティを構成できる WebSocketService サービスを提供して WebSocketHandlerAdapter Bean を作成する必要があります。例：

Web MVC

@EnableWebFlux は DelegatingWebFluxConfiguration をインポートします:

拡張モードの場合、次の例に示すように、WebFluxConfigurer を実装する代わりに、@EnableWebFlux を削除して DelegatingWebFluxConfiguration から直接拡張できます。

既存のメソッドを WebConfig に保持できますが、ベースクラスからの Bean 宣言をオーバーライドしても、クラスパスに他の WebMvcConfigurer 実装をいくつでも持つことができます。

コーデックには、アプリケーションのメモリの課題を回避するために、メモリにデータをバッファリングするための制限があります。デフォルトでは、これらは 256KB に設定されています。それでも不十分な場合は、次のエラーが発生します。

デフォルトコーデックの制限を変更するには、以下を使用します。

Reactor Netty 設定をカスタマイズするには、事前構成された HttpClient を提供します。

次の例は、Jetty HttpClient 設定をカスタマイズする方法を示しています。

デフォルトでは、HttpClient は独自のリソース（Executor、ByteBufferPool、Scheduler）を作成し、プロセスが終了するか stop() が呼び出されるまでアクティブのままになります。

次の例に示すように、型 JettyResourceFactory の Spring 管理 Bean を宣言することにより、Jetty クライアント（およびサーバー）の複数のインスタンス間でリソースを共有し、Spring ApplicationContext が閉じられたときにリソースを確実にシャットダウンできます。

次の例は、Apache HttpComponents HttpClient 設定をカスタマイズする方法を示しています。

フォームデータを送信するには、MultiValueMap<String, String> を本文として提供できます。コンテンツは FormHttpMessageWriter によって application/x-www-form-urlencoded に自動的に設定されることに注意してください。次の例は、MultiValueMap<String, String> の使用方法を示しています。

次の例に示すように、BodyInserters を使用してインラインでフォームデータを提供することもできます。

マルチパートデータを送信するには、パーツのコンテンツを表す Object インスタンスまたはパーツのコンテンツとヘッダーを表す HttpEntity インスタンスのいずれかである MultiValueMap<String, ?> を提供する必要があります。MultipartBodyBuilder は、マルチパートリクエストを準備するための便利な API を提供します。次の例は、MultiValueMap<String, ?> を作成する方法を示しています。

ほとんどの場合、各パーツに Content-Type を指定する必要はありません。コンテンツ型は、シリアライズするために選択された HttpMessageWriter に基づいて、または Resource の場合はファイル拡張子に基づいて自動的に決定されます。必要に応じて、オーバーロードされたビルダー part メソッドのいずれかを使用して、各パーツに使用する MediaType を明示的に提供できます。

MultiValueMap を準備したら、次の例に示すように、WebClient に渡す最も簡単な方法は body メソッドを使用することです。

MultiValueMap に少なくとも 1 つの String 以外の値（通常のフォームデータ（つまり application/x-www-form-urlencoded）を表す場合もある）が含まれている場合、Content-Type を multipart/form-data に設定する必要はありません。これは、MultipartBodyBuilder を使用する場合に常に当てはまり、HttpEntity ラッパーが保証されます。

MultipartBodyBuilder の代替として、次の例に示すように、組み込みの BodyInserters を介して、インラインスタイルのマルチパートコンテンツを提供することもできます。

WebSocket は HTTP 互換であるように設計されており、HTTP リクエストで始まりますが、2 つのプロトコルが非常に異なるアーキテクチャとアプリケーションプログラミングモデルにつながることを理解することが重要です。

HTTP および REST では、アプリケーションは多くの URL としてモデル化されます。アプリケーションと対話するために、クライアントはこれらの URL にアクセスし、リクエスト / レスポンススタイルを使用します。サーバーは、HTTP URL、メソッド、ヘッダーに基づいてリクエストを適切なハンドラーにルーティングします。

対照的に、WebSockets では、通常、最初の接続用の URL は 1 つだけです。その後、すべてのアプリケーションメッセージは同じ TCP 接続で流れます。これは、まったく異なる非同期のイベント駆動型のメッセージングアーキテクチャを指します。

WebSocket は低レベルのトランスポートプロトコルでもあり、HTTP とは異なり、メッセージのコンテンツにセマンティクスを規定していません。つまり、クライアントとサーバーがメッセージのセマンティクスに同意しない限り、メッセージをルーティングまたは処理する方法はありません。

WebSocket クライアントおよびサーバーは、HTTP ハンドシェイクリクエストの Sec-WebSocket-Protocol ヘッダーを介して、より高いレベルのメッセージングプロトコル（たとえば、STOMP）の使用をネゴシエートできます。それがなければ、彼らは彼ら自身の規約を考え出す必要があります。

WebSockets は、Web ページを動的かつインタラクティブにすることができます。ただし、多くの場合、Ajax と HTTP ストリーミングまたはロングポーリングの組み合わせにより、シンプルで効果的なソリューションを提供できます。

例: ニュース、メール、ソーシャルフィードは動的に更新する必要がありますが、数分ごとに更新しても問題ありません。一方、コラボレーション、ゲーム、金融アプリは、リアルタイムにさらに近づける必要があります。

遅延だけが決定要因ではありません。メッセージの量が比較的少ない場合（ネットワーク障害の監視など）、HTTP ストリーミングまたはポーリングは効果的なソリューションを提供できます。WebSocket の使用に最適なのは、低レイテンシー、高周波数、高ボリュームの組み合わせです。

また、インターネット上では、Upgrade ヘッダーを渡すように構成されていないか、アイドル状態であると思われる長寿命の接続を閉じるため、コントロール外の制限プロキシが WebSocket 相互作用を妨げる可能性があることに注意してください。これは、ファイアウォール内の内部アプリケーションに WebSocket を使用することは、一般公開アプリケーションよりも簡単な決定であることを意味します。

サーブレットスタックと同じ

WebSocket サーバーを作成するには、最初に WebSocketHandler を作成できます。次の例は、その方法を示しています。

次に、それを URL にマップできます。

WebFlux 構成を使用している場合は、これ以上何もする必要はありません。そうでない場合は、WebFlux 構成を使用していない場合は、以下に示すように WebSocketHandlerAdapter を宣言する必要があります。

WebSocketHandler の handle メソッドは、WebSocketSession を取得して Mono<Void> を返し、セッションのアプリケーション処理が完了したことを示します。セッションは、受信メッセージ用と送信メッセージ用の 2 つのストリームを介して処理されます。次の表に、ストリームを処理する 2 つのメソッドを示します。

WebSocketHandler は、受信ストリームと送信ストリームを統合されたフローに構成し、そのフローの完了を反映する Mono<Void> を返す必要があります。アプリケーション要件に応じて、統合フローは次の場合に完了します。

受信と送信のメッセージストリームが一緒に構成される場合、Reactive Streams は終了アクティビティを通知するため、接続が開いているかどうかを確認する必要はありません。受信ストリームは完了またはエラーシグナルを受信し、送信ストリームはキャンセルシグナルを受信します。

ハンドラーの最も基本的な実装は、受信ストリームを処理するものです。次の例は、このような実装を示しています。

次の実装では、受信ストリームと送信ストリームを組み合わせます。

次の例に示すように、受信ストリームと送信ストリームは独立しており、完了のためにのみ結合できます。

DataBuffer は、WebFlux のバイトバッファーの表現です。参照の Spring コア部分は、データバッファとコーデックのセクションでさらに詳しく説明しています。理解すべき重要な点は、Netty のような一部のサーバーでは、バイトバッファーがプールされ、参照カウントされ、メモリリークを避けるために消費されたときに解放する必要があるということです。

Netty で実行する場合、アプリケーションが解放されないように入力データバッファーを保持する場合は、DataBufferUtils.retain(dataBuffer) を使用し、その後バッファーが消費されるときに DataBufferUtils.release(dataBuffer) を使用する必要があります。

サーブレットスタックと同じ

WebSocketHandlerAdapter は WebSocketService に委譲します。デフォルトでは、これは HandshakeWebSocketService のインスタンスであり、WebSocket リクエストに対して基本的なチェックを実行してから、使用中のサーバーに RequestUpgradeStrategy を使用します。現在、Reactor Netty、Tomcat、Jetty、Undertow のサポートが組み込まれています。

HandshakeWebSocketService は Predicate<String> を設定して WebSession から属性を抽出し、WebSocketSession の属性に挿入できる sessionAttributePredicate プロパティを公開します。