跳到主要内容

功能端点

ChatGPT-4o 中英对照 Functional Endpoints

Spring WebFlux 包含 WebFlux.fn，这是一种轻量级的函数式编程模型，其中使用函数来路由和处理请求，并且契约被设计为不可变的。它是基于注解的编程模型的替代方案，但在其他方面运行在相同的 Reactive Core 基础之上。

概述​

在 WebFlux.fn 中，HTTP 请求由一个 HandlerFunction 处理：一个接收 ServerRequest 并返回延迟 ServerResponse（即 Mono<ServerResponse>）的函数。请求和响应对象都有不可变的契约，提供对 HTTP 请求和响应的 JDK 8 友好访问。HandlerFunction 相当于基于注解的编程模型中的 @RequestMapping 方法的主体。

传入的请求通过一个 RouterFunction 路由到一个处理函数：这是一个接受 ServerRequest 并返回延迟的 HandlerFunction（即 Mono<HandlerFunction>）的函数。当路由器函数匹配时，返回一个处理函数；否则返回一个空的 Mono。RouterFunction 相当于 @RequestMapping 注解，但主要区别在于路由器函数不仅提供数据，还提供行为。

RouterFunctions.route() 提供了一个路由器构建器，方便创建路由器，如下例所示：

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

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

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

public class PersonHandler {

    // ...

    public Mono<ServerResponse> listPeople(ServerRequest request) {
        // ...
    }

    public Mono<ServerResponse> createPerson(ServerRequest request) {
        // ...
    }

    public Mono<ServerResponse> getPerson(ServerRequest request) {
        // ...
    }
}
java

  • 使用 route() 创建路由。

运行 RouterFunction 的一种方法是将其转换为 HttpHandler，并通过内置的服务器适配器之一安装它：

  • RouterFunctions.toHttpHandler(RouterFunction)

  • RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)

大多数应用程序可以通过 WebFlux Java 配置运行，请参阅运行服务器。

HandlerFunction​

ServerRequest 和 ServerResponse 是不可变接口，提供了对 HTTP 请求和响应的 JDK 8 友好访问。请求和响应都对主体流提供 Reactive Streams 的背压。请求体用 Reactor 的 Flux 或 Mono 表示。响应体用任何 Reactive Streams 的 Publisher 表示，包括 Flux 和 Mono。有关更多信息，请参见 Reactive Libraries。

ServerRequest​

ServerRequest 提供对 HTTP 方法、URI、头信息和查询参数的访问，而对主体的访问则通过 body 方法提供。

以下示例将请求主体提取为一个 Mono<String>：

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

以下示例将主体提取为 Flux<Person>（或 Kotlin 中的 Flow<Person>），其中 Person 对象从某种序列化形式（如 JSON 或 XML）解码而来：

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

前面的示例是使用更通用的 ServerRequest.body(BodyExtractor) 的快捷方式，该方法接受 BodyExtractor 功能策略接口。工具类 BodyExtractors 提供了多个实例的访问。例如，前面的示例也可以写成如下形式：

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

以下示例展示了如何访问表单数据：

Mono<MultiValueMap<String, String>> map = request.formData();
java

下面的示例展示了如何将多部分数据作为映射来访问：

Mono<MultiValueMap<String, Part>> map = request.multipartData();
java

下面的示例展示了如何以流式方式一次访问一个多部分数据：

Flux<PartEvent> allPartEvents = request.bodyToFlux(PartEvent.class);
allPartsEvents.windowUntil(PartEvent::isLast)
      .concatMap(p -> p.switchOnFirst((signal, partEvents) -> {
          if (signal.hasValue()) {
              PartEvent event = signal.get();
              if (event instanceof FormPartEvent formEvent) {
                  String value = formEvent.value();
                  // handle form field
              }
              else if (event instanceof FilePartEvent fileEvent) {
                  String filename = fileEvent.filename();
                  Flux<DataBuffer> contents = partEvents.map(PartEvent::content);
                  // handle file upload
              }
              else {
                  return Mono.error(new RuntimeException("Unexpected event: " + event));
              }
          }
          else {
              return partEvents; // either complete or error signal
          }
      }));
java

请注意，必须完全消费、转发或释放 PartEvent 对象的主体内容，以避免内存泄漏。

ServerResponse​

ServerResponse 提供对 HTTP 响应的访问，并且由于它是不可变的，你可以使用 build 方法来创建它。你可以使用构建器来设置响应状态、添加响应头或提供响应体。以下示例创建了一个带有 JSON 内容的 200 (OK) 响应：

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

下面的示例展示了如何构建一个带有 Location 头部且无主体的 201 (CREATED) 响应：

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

根据使用的编解码器，可以传递提示参数来自定义如何序列化或反序列化主体。例如，指定一个 Jackson JSON 视图：

ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView.class).body(...);
java

处理器类​

我们可以将处理函数写为一个 lambda，如以下示例所示：

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

这很方便，但在一个应用程序中我们需要多个函数，多个内联 lambda 可能会变得混乱。因此，将相关的处理函数组合到一个处理类中是有用的，它的作用类似于基于注解的应用程序中的 @Controller。例如，下面的类公开了一个响应式的 Person 仓库：

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.reactive.function.server.ServerResponse.ok;

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 ok().contentType(APPLICATION_JSON).body(people, Person.class);
    }

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

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

  • listPeople 是一个处理函数，它以 JSON 格式返回在仓库中找到的所有 Person 对象。

  • createPerson 是一个处理函数，它存储请求体中包含的新 Person。注意 PersonRepository.savePerson(Person) 返回 Mono<Void>：一个空的 Mono，当从请求中读取并存储了 person 时，它会发出一个完成信号。所以我们使用 build(Publisher<Void>) 方法在接收到该完成信号时发送响应（即 Person 已保存）。

  • getPerson 是一个处理函数，它返回由 id 路径变量标识的单个人。如果在仓库中找到该 Person，我们将其检索并创建一个 JSON 响应。如果未找到，我们使用 switchIfEmpty(Mono<T>) 返回 404 Not Found 响应。

验证​

一个功能性端点可以使用 Spring 的验证工具对请求体进行验证。例如，给定一个自定义的 Spring Validator 实现用于 Person：

public class PersonHandler {

    private final Validator validator = new PersonValidator(); 1

    // ...

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

    private void validate(Person person) {
        Errors errors = new BeanPropertyBindingResult(person, "person");
        validator.validate(person, errors);
        if (errors.hasErrors()) {
            throw new ServerWebInputException(errors.toString()); 3
        }
    }
}
java

  • 创建 Validator 实例。

  • 应用验证。

  • 抛出异常以返回 400 响应。

处理程序还可以通过创建和注入基于 LocalValidatorFactoryBean 的全局 Validator 实例来使用标准的 bean 验证 API（JSR-303）。请参阅Spring 验证。

RouterFunction​

路由器函数用于将请求路由到相应的 HandlerFunction。通常，你不需要自己编写路由器函数，而是使用 RouterFunctions 工具类上的方法来创建一个。RouterFunctions.route()（无参数）为你提供了一个流畅的构建器，用于创建路由器函数，而 RouterFunctions.route(RequestPredicate, HandlerFunction) 则提供了一种直接创建路由器的方法。

通常，建议使用 route() 构建器，因为它为典型的映射场景提供了方便的快捷方式，而无需难以发现的静态导入。例如，路由器函数构建器提供了方法 GET(String, HandlerFunction) 来创建 GET 请求的映射；以及 POST(String, HandlerFunction) 用于 POST 请求。

除了基于 HTTP 方法的映射之外，路由构建器还提供了一种在映射到请求时引入附加谓词的方法。对于每个 HTTP 方法，都有一个重载变体，它将 RequestPredicate 作为参数，通过它可以表达附加约束。

断言​

您可以编写自己的 RequestPredicate，但 RequestPredicates 工具类提供了常用的实现，基于请求路径、HTTP 方法、内容类型等。以下示例使用请求谓词基于 Accept 头创建约束：

RouterFunction<ServerResponse> route = RouterFunctions.route()
    .GET("/hello-world", accept(MediaType.TEXT_PLAIN),
        request -> ServerResponse.ok().bodyValue("Hello World")).build();
java

您可以通过使用以下方法将多个请求谓词组合在一起：

  • RequestPredicate.and(RequestPredicate) — 两者都必须匹配。

  • RequestPredicate.or(RequestPredicate) — 任意一个可以匹配。

RequestPredicates 中的许多谓词是组合而成的。例如，RequestPredicates.GET(String) 是由 RequestPredicates.method(HttpMethod) 和 RequestPredicates.path(String) 组合而成的。上面展示的示例也使用了两个请求谓词，因为构建器在内部使用了 RequestPredicates.GET，并将其与 accept 谓词组合在一起。

路由​

路由器函数按顺序进行评估：如果第一个路由不匹配，则评估第二个，以此类推。因此，在声明路由时，先声明更具体的路由再声明一般的路由是有意义的。这在将路由器函数注册为 Spring bean 时也很重要，稍后将对此进行描述。请注意，这种行为与基于注解的编程模型不同，在基于注解的模型中，会自动选择“最具体”的控制器方法。

当使用路由器函数构建器时，所有定义的路由都会被组合成一个从 build() 返回的 RouterFunction。还有其他方法可以将多个路由器函数组合在一起：

  • 在 RouterFunctions.route() 构建器上使用 add(RouterFunction)

  • RouterFunction.and(RouterFunction)

  • RouterFunction.andRoute(RequestPredicate, HandlerFunction) — 是使用嵌套的 RouterFunctions.route() 的 RouterFunction.and() 的快捷方式。

下面的示例展示了四条路线的组合：

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> otherRoute = ...

RouterFunction<ServerResponse> route = route()
    .GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) 1
    .GET("/person", accept(APPLICATION_JSON), handler::listPeople) 2
    .POST("/person", handler::createPerson) 3
    .add(otherRoute) 4
    .build();
java

  • GET /person/{id} 带有匹配 JSON 的 Accept 头被路由到 PersonHandler.getPerson

  • GET /person 带有匹配 JSON 的 Accept 头被路由到 PersonHandler.listPeople

  • POST /person 没有额外的谓词被映射到 PersonHandler.createPerson，并且

  • otherRoute 是一个在其他地方创建的路由函数，并被添加到构建的路由中。

嵌套路由​

一组路由函数通常会有一个共享的谓词，例如一个共享的路径。在上面的例子中，共享的谓词是一个匹配 /person 的路径谓词，被三个路由使用。当使用注解时，你可以通过使用映射到 /person 的类型级别 @RequestMapping 注解来消除这种重复。在 WebFlux.fn 中，可以通过路由函数构建器上的 path 方法共享路径谓词。例如，上面例子的最后几行可以通过使用嵌套路由进行如下改进：

RouterFunction<ServerResponse> route = route()
    .path("/person", builder -> builder 1
        .GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)
        .GET(accept(APPLICATION_JSON), handler::listPeople)
        .POST(handler::createPerson))
    .build();
java

  • 注意，path 的第二个参数是一个接受路由构建器的消费者。

尽管基于路径的嵌套是最常见的，但你可以通过在构建器上使用 nest 方法来对任何类型的谓词进行嵌套。上面的例子中仍然包含一些共享的 Accept 头谓词形式的重复。我们可以通过将 nest 方法与 accept 结合使用来进一步改进：

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople))
        .POST(handler::createPerson))
    .build();
java

提供资源​

WebFlux.fn 提供了对资源服务的内置支持。

备注

除了下面描述的功能之外，还可以通过 RouterFunctions#resource(java.util.function.Function) 实现更灵活的资源处理。

重定向到资源​

可以将符合指定谓词的请求重定向到某个资源。例如，这在处理单页应用程序中的重定向时非常有用。

ClassPathResource index = new ClassPathResource("static/index.html");
List<String> extensions = List.of("js", "css", "ico", "png", "jpg", "gif");
RequestPredicate spaPredicate = path("/api/**").or(path("/error")).or(pathExtension(extensions::contains)).negate();
RouterFunction<ServerResponse> redirectToIndex = route()
    .resource(spaPredicate, index)
    .build();
java

从根位置提供资源​

还可以将与给定模式匹配的请求路由到相对于给定根位置的资源。

Resource location = new FileUrlResource("public-resources/");
RouterFunction<ServerResponse> resources = RouterFunctions.resources("/resources/**", location);
java

运行服务器​

如何在 HTTP 服务器中运行路由器函数？一个简单的选项是通过使用以下方法之一将路由器函数转换为 HttpHandler：

  • RouterFunctions.toHttpHandler(RouterFunction)

  • RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)

然后，您可以按照 HttpHandler 中的服务器特定说明，将返回的 HttpHandler 与多个服务器适配器一起使用。

一个更典型的选项，也是 Spring Boot 使用的选项，是通过 WebFlux 配置使用基于 DispatcherHandler 的设置，该设置使用 Spring 配置来声明处理请求所需的组件。WebFlux Java 配置声明了以下基础设施组件以支持函数式端点：

  • RouterFunctionMapping：检测 Spring 配置中的一个或多个 RouterFunction<?> bean，对它们进行排序，通过 RouterFunction.andOther 组合它们，并将请求路由到最终组合的 RouterFunction。

  • HandlerFunctionAdapter：简单的适配器，使 DispatcherHandler 能够调用映射到请求的 HandlerFunction。

  • ServerResponseResultHandler：通过调用 ServerResponse 的 writeTo 方法来处理 HandlerFunction 调用的结果。

前面的组件使功能性端点能够适应 DispatcherHandler 请求处理生命周期，并且（可能）与注解控制器并行运行（如果有声明的话）。这也是 Spring Boot WebFlux starter 启用功能性端点的方式。

下面的示例展示了一个 WebFlux Java 配置（参见 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
    public void addCorsMappings(CorsRegistry registry) {
        // configure CORS...
    }

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

过滤处理函数​

你可以通过在路由函数构建器上使用 before、after 或 filter 方法来过滤处理函数。使用注解，你可以通过 @ControllerAdvice、ServletFilter 或两者结合来实现类似的功能。过滤器将应用于由构建器构建的所有路由。这意味着在嵌套路由中定义的过滤器不适用于“顶级”路由。例如，考虑以下示例：

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople)
            .before(request -> ServerRequest.from(request) 1
                .header("X-RequestHeader", "Value")
                .build()))
        .POST(handler::createPerson))
    .after((request, response) -> logResponse(response)) 2
    .build();
java

  • 添加自定义请求头的 before 过滤器仅应用于两个 GET 路由。

  • 记录响应的 after 过滤器应用于所有路由，包括嵌套路由。

路由器构建器上的 filter 方法接受一个 HandlerFilterFunction：一个函数，该函数接收一个 ServerRequest 和 HandlerFunction 并返回一个 ServerResponse。处理程序函数参数表示链中的下一个元素。这通常是被路由到的处理程序，但如果应用了多个过滤器，它也可以是另一个过滤器。

现在我们可以为我们的路由添加一个简单的安全过滤器，假设我们有一个 SecurityManager 可以确定某个特定路径是否被允许。下面的示例展示了如何实现：

SecurityManager securityManager = ...

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople))
        .POST(handler::createPerson))
    .filter((request, next) -> {
        if (securityManager.allowAccessTo(request.path())) {
            return next.handle(request);
        }
        else {
            return ServerResponse.status(UNAUTHORIZED).build();
        }
    })
    .build();
java

前面的示例表明调用 next.handle(ServerRequest) 是可选的。我们仅在允许访问时才运行处理函数。

除了在路由函数构建器上使用 filter 方法之外，还可以通过 RouterFunction.filter(HandlerFilterFunction) 将过滤器应用于现有的路由函数。

备注

功能端点的 CORS 支持是通过专用的 CorsWebFilter 提供的。