webflux-reactive-patterns

WebFlux のリアクティブパターン

リクエスト経路全体でノンブロッキング I/O のメリットが得られる場合は、WebFlux を使用します。

依存関係とパイプラインのルール

• 専用の Boot 4 WebFlux および WebFlux テストスターターを使用します。
• Mono または Flux を返します。リクエスト処理コードで subscribe() を呼び出してはいけません。
• 順序要件に応じて、flatMap、concatMap、または逐次合成を選択します。
• JDBC、ファイルシステム、ブロッキングを伴う SDK 呼び出しを Reactor のイベントループ上で実行しないでください。
• 避けられないブロッキング処理は、アダプターの境界で boundedElastic に分離します。
• 外部呼び出しにタイムアウトを設定し、キャンセルを保持します。

コンテキストとエラー

• リクエストスコープのメタデータは ThreadLocal ではなく Reactor の Context に格納します。
• オブザーバビリティのコンテキスト伝播を意図的に設定します。
• キャンセルを握りつぶさず、ドメインエラーを一元的に変換します。
• onErrorResume は明確に定義されたフォールバックにのみ使用し、onErrorContinue は避けます。

永続化とストリーミング

• リアクティブなデータベースアクセスには R2DBC を使用します。
• 下流の処理能力に応じて、ファンアウトの同時実行数を制限します。
• バックプレッシャー、バッファリング、最大メモリ内サイズを定義します。
• 下流のコードを簡潔にするためだけに、無制限のストリームをすべて収集してはいけません。

テスト

• パブリッシャーの動作には StepVerifier を、コントラクトのテストには WebTestClient を使用します。
• キャンセル、タイムアウト、結果なし、エラー、順序、バックプレッシャーをテストします。
• 実用的な場合は、テストでブロッキング呼び出しを検出します。

例

• examples/good-reactive-service.java と examples/bad-reactive-service.java を参照してください。

公式ソース

• Spring WebFlux：https://docs.spring.io/spring-framework/reference/web/webflux.html
• Reactor リファレンス：https://projectreactor.io/docs/core/release/reference/
• Spring Data R2DBC：https://docs.spring.io/spring-data/relational/reference/r2dbc.html

注意点

• エージェントが MVC と WebFlux のスターターを誤って追加する場合があります。意図した Web スタックを選択してください。
• エージェントがアプリケーションの処理フローで block() または subscribe() を呼び出す場合があります。サブスクリプションはランタイムに任せてください。
• エージェントがテナントやトレースのデータに ThreadLocal を使用する場合があります。Reactor の Context を使用してください。
• エージェントが同時実行数に上限のない flatMap を使用する場合があります。下流の制限に基づいて同時実行数を設定してください。
• エージェントが JDBC を Mono.just でラップする場合があります。これでもイベントループはブロックされます。