Web on Reactive Stack(version 5.0.3.RELEASE) 1. Spring WebFluxをテキトーに訳した（1.5 - 1.9）

1.5. Functional Endpoints

Spring WebFluxには、軽量な関数型プログラミングモデルがあり、関数ではルーティング・リクエスト処理とイミュータブルな設計を行います。アノテーションベースとは別のプログラミングモデルですが、基礎部分で動作するReactive Spring Webは同一です。

1.5.1. HandlerFunction

HTTPリクエストはHandlerFunctionで処理し、これは基本的にはServerRequestを受け取ってMono<ServerResponse>を返す関数です。アノテーションベースを知っているユーザ向けに言えば、ハンドラファクションは@RequestMappingメソッドに相当します。

ServerRequestとServerResponseはイミュータブルなインタフェースで、基底のHTTPメッセージにJDK-8らしいやり方でアクセスを提供します。アクセスはReactive Streamsのノンブロッキングバックプレッシャで行います。リクエストはReactorのFluxもしくはMonoでボディを公開し、レスポンスはボディとしてReactive StreamsのPublisherをアクセプトします。これの合理性についてはReactive Librariesで解説します。

ServerRequestはHTTPリクエストの各種要素、メソッド・URI・クエリパラメータ・ヘッダー（ServerRequest.Headers経由）、へのアクセスを提供します。ボディへのアクセスはbodyメソッドで行います。たとえば、以下はリクエストボディをMono<String>に抽出します。

Mono<String> string = request.bodyToMono(String.class);

また、以下はボディをFluxに抽出する方法で、Personはボディのコンテンツからデシリアライズするクラスです（つまりボディがJSON, JAXB（XMLの場合）を含む場合PersonクラスはJacksonが処理する）。

Flux<Person> people = request.bodyToFlux(Person.class);

上述のbodyToMonoとbodyToFluxはジェネリックなServerRequest.body(BodyExtractor)メソッドを使用する便利なメソッドです。BodyExtractorは関数型のストラテジインタフェースで、自前の抽出ロジックを書くものですが、一般的なBodyExtractorのインスタンスは```BodyExtractors````ユーティリティクラスにあります。よって、上記サンプルは以下のようにも書けます。

Mono<String> string = request.body(BodyExtractors.toMono(String.class);
Flux<Person> people = request.body(BodyExtractors.toFlux(Person.class);

同様に、ServerResponseはHTTPレスポンスへのアクセスを提供します。これはイミュータブルなので、ビルダーでServerResponseを生成します。ビルダーで、レスポンスステータス・レスポンスヘッダーの追加・ボディの指定、が出来ます。たとえば、レスポンスを、200 OKステータス・JSONコンテンツタイプ・ボディ指定、で作るには以下のようにします。

Mono<Person> person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);

また、以下は、201 CREATEDステータス・"Location"ヘッダー・空のボディ、のレスポンスを作ります。

URI location = ...
ServerResponse.created(location).build();

HandlerFunctionをこれらを使用して作れます。たとえば、以下はごく単純な"Hello World"なラムダのハンドラーで、200 ステータス・ボディにString、のレスポンスを返します。

HandlerFunction<ServerResponse> helloWorld =
  request -> ServerResponse.ok().body(fromObject("Hello World"));

上述のように、ラムダでハンドラ関数を簡単に書けますが、場合によっては可読性を損なうので、複数の関数がある場合はメンテナンス性が悪くなります。よって、単一のハンドラかコントローラに、関連するハンドラ関数をグループ化することを推奨します。たとえば、以下はreactiveのPersonリポジトリを公開するクラスです。

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.reactive.function.BodyInserters.fromObject;

public class PersonHandler {

    private final PersonRepository repository;

    public PersonHandler(PersonRepository repository) {
        this.repository = repository;
    }

    public Mono<ServerResponse> listPeople(ServerRequest request) { // 1.
        Flux<Person> people = repository.allPeople();
        return ServerResponse.ok().contentType(APPLICATION_JSON).body(people, Person.class);
    }

    public Mono<ServerResponse> createPerson(ServerRequest request) { // 2.
        Mono<Person> person = request.bodyToMono(Person.class);
        return ServerResponse.ok().build(repository.savePerson(person));
    }

    public Mono<ServerResponse> getPerson(ServerRequest request) { // 3.
        int personId = Integer.valueOf(request.pathVariable("id"));
        Mono<ServerResponse> notFound = ServerResponse.notFound().build();
        Mono<Person> personMono = repository.getPerson(personId);
        return personMono
                .flatMap(person -> ServerResponse.ok().contentType(APPLICATION_JSON).body(fromObject(person)))
                .switchIfEmpty(notFound);
    }
}

listPeopleはJSONでリポジトリのすべてのPersionオブジェクトを返します。
createPersonはリクエストボディ内のPersionを新規作成します。PersonRepository.savePerson(Person)はMono<Void>を返す点に注意してください。personがリクエストから読み込まれて保存されると、空のMonoは完了シグナルを出します。完了シグナル受信時、つまりPerson保存完了時、にレスポンスを送信するにはbuild(Publisher<Void>)を使うことになります。
getPersonはパス変数にIDを指定して単一のpersonを返すハンドラー関数です。リポジトリからPersonを取得し、もし存在すればJSONレスポンスを生成します。無ければ、switchIfEmpty(Mono<T>)で404 Not Foundレスポンスを返しています。

1.5.2. RouterFunction

リクエストはRouterFunctionがハンドラー関数にルーティングします。RouterFunctionの関数はServerRequestを受け取ってMono<HandlerFunction>を返します。リクエストがある特定のルーティングにマッチするとハンドラ関数が返され、マッチしない場合は空のMonoが返されます。アノテーションベースを知っているユーザ向けに言えば、RouterFunctionは@RequestMappingアノテーションに相当します。

基本的には、ルータ―関数を自身で書くことはありませんが、リクエスト述語とハンドラ関数でルータ関数を生成するにはRouterFunctions.route(RequestPredicate, HandlerFunction)を使います。述語が適用可能な場合、そのリクエストはハンドラー関数にルーティングが行われ、そうでない場合ルーティングは実行されず、404 Not Foundレスポンスが返されます。自前のRequestPredicateを書くことは可能ですが、そうする必要は無く、良くある一般的な述語はRequestPredicatesユーティリティクラスにあり、例えば、パスペース・HTTPメソッド・コンテンツタイプなどでのマッチングです。routeを使用する、"Hello World"なハンドラ―関数へのルーティングの記述は以下のようになります。

RouterFunction<ServerResponse> helloWorldRoute =
    RouterFunctions.route(RequestPredicates.path("/hello-world"),
    request -> Response.ok().body(fromObject("Hello World")));

二つのルータ関数を一つの複合ルータ関数にまとめることが出来ます。最初のルーティングの述語にマッチしない場合、二つ目が評価されます。複合ルータ関数はそれぞれ順に評価されるので、狭い述語を先に置き、より汎用の述語を後に置きます。RouterFunction.and(RouterFunction)かRouterFunction.andRoute(RequestPredicate, HandlerFunction)で二つのルータ関数を複合化します。後者はRouterFunction.and()とRouterFunctions.route()を組み合わせて一度にやるものです。

上述したPersonHandlerを例にとると、個々のハンドラへのルータ関数は以下のように定義します。ハンドラ関数の参照はメソッド参照を使用しています。

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.reactive.function.server.RequestPredicates.*;

PersonRepository repository = ...
PersonHandler handler = new PersonHandler(repository);

RouterFunction<ServerResponse> personRoute =
    route(GET("/person/{id}").and(accept(APPLICATION_JSON)), handler::getPerson)
        .andRoute(GET("/person").and(accept(APPLICATION_JSON)), handler::listPeople)
        .andRoute(POST("/person").and(contentType(APPLICATION_JSON)), handler::createPerson);

ルータ関数では、RequestPredicate.and(RequestPredicate)かRequestPredicate.or(RequestPredicate)で、リクエスト述語の組み合わせを指定しています。これらの動作は見た目ままで、andは与えられた述語が両方ともマッチした場合で、orはどちらかです。RequestPredicatesの述語の多くが複合になっています。たとえば、RequestPredicates.GET(String)はRequestPredicates.method(HttpMethod)とRequestPredicates.path(String)の複合です。

1.5.3. Running a server

HTTPサーバでのルータ関数の動かし方について。最もシンプルなやり方はルータ関数を以下のいずれかの手段でHttpHandlerに変換します。

RouterFunctions.toHttpHandler(RouterFunction)
RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)

戻り値のHttpHandlerは各種サーバ固有のアダプタで使用可能で、以下のHttpHandlerに示す通りです。

別の方法として、WebFlux Configを使用するDispatcherHandlerベースのセットアップで動かす方法があります。WebFlux Configはリクエスト処理に必要となるコンポーネントを宣言するのにSpring configurationを使用します。WebFlux Java configは以下のファンクショナルエンドポイント用の基盤コンポーネントを宣言します。

RouterFunctionMapping - Spring configurationで一つ以上のRouterFunction<?>を検出すると、それらをRouterFunction.andOtherで複合化し、出来たRouterFunctionにリクエストをルーティングする。
HandlerFunctionAdapter - リクエストにマッピングされているHandlerFunctionをDispatcherHandlerが呼び出すためのシンプルなアダプタ。
ServerResponseResultHandler - HandlerFunctionの呼び出し結果をServerResponseのwriteToを呼び出すことで処理する。

上述のコンポーネントはDispatcherHandlerのリクエスト処理ライフサイクルにファンクショナルエンドポイントをフィットさせるためのもので、同時に、アノテーションのコントローラがもし存在すればこれと並存させるためのものでもあります。また、Spring Boot WebFlux starterがファンクショナルエンドポイントを有効化する方法でもあります。

以下はWebFlux Java configの例です。（動かし方はDispatcherHandler参照）

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Bean
    public RouterFunction<?> routerFunctionA() {
        // ...
    }

    @Bean
    public RouterFunction<?> routerFunctionB() {
        // ...
    }

    // ...

    @Override
    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
        // configure message conversion...
    }

    @Override
    default void addCorsMappings(CorsRegistry registry) {
        // configure CORS...
    }

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        // configure view resolution for HTML rendering...
    }
}

1.5.4. HandlerFilterFunction

ルータ関数でマッピングしたルーティングはRouterFunction.filter(HandlerFilterFunction)でフィルタをかけられます。HandlerFilterFunctionはServerRequestとHandlerFunctionを受け取りServerResponseを返す関数です。このハンドラ関数の引数はチェーンの次の要素で、基本的にはルーティング先のHandlerFunctionですが、複数のフィルタが適用される場合は別のFilterFunctionになる場合があります。アノテーションベースの類似機能は@ControllerAdvice and/or ServletFilterで実現できます。いま、ルーティングにセキュリティフィルタを追加するとして、特定のパスが許可されるかどうかを判定するSecurityManagerが既にあるとします。

import static org.springframework.http.HttpStatus.UNAUTHORIZED;

SecurityManager securityManager = ...
RouterFunction<ServerResponse> route = ...

RouterFunction<ServerResponse> filteredRoute =
    route.filter((request, next) -> {
        if (securityManager.allowAccessTo(request.path())) {
            return next.handle(request);
        }
        else {
            return ServerResponse.status(UNAUTHORIZED).build();
        }
  });

上記の例にあるようにnext.handle(ServerRequest)は必ずしも呼ぶ必要はありません。上記ではアクセスを許可する場合にだけハンドラ関数を呼び出しています。

ファンクショナルエンドポイントでのCORSはCorsWebFilterで行っています。

1.5. Functional Endpoints

1.5.1. HandlerFunction

1.5.2. RouterFunction

1.5.3. Running a server

1.5.4. HandlerFilterFunction

1.6. CORS

1.6.1. Introduction

1.6.2. Processing

1.6.3. @CrossOrigin

1.6.4. Global Config

1.6.5. CORS WebFilter

1.7. Web Security

1.8. WebFlux Config

1.8.1. Enable WebFlux config

1.8.2. WebFlux config API

1.8.3. Conversion, formatting

1.8.4. Validation

1.8.5. Content type resolvers

1.8.6. HTTP message codecs

1.8.7. View resolvers

1.8.8. Static resources

1.8.9. Path Matching

1.8.10. Advanced config mode

1.9. HTTP/2