Reactive 栈的 Web 应用

我们谈到了 "非阻塞" 和 "函数式"，但响应式是什么意思？

术语 “reactive”（响应式）， 指的是围绕对变化做出反应的编程模型—​对I/O事件做出反应的网络组件，对鼠标事件做出反应的UI controller，以及其他。从这个意义上说，非阻塞就是响应式，因为，我们现在不是被阻塞，而是在操作完成或数据可用时对通知做出反（响）应。

还有一个重要的机制，我们Spring团队将其与 "响应式" 联系在一起，那就是非阻塞式背压。在同步的、命令式的代码中，阻塞式调用是一种自然的背压形式，迫使调用者等待。在非阻塞代码中，控制事件的速度变得很重要，这样快速的生产者就不会压倒其“消费者”。

Reactive Streams是一个 小型规范（也在Java 9中 采用），它定义了异步组件之间的互动，具有背压。例如，一个 data repository（作为 Publisher）可以产生数据，然后由一个HTTP服务器（作为 Subscriber）写入响应。Reactive Streams 的主要目的是让订阅者控制发布者产生数据的快慢。

Reactive Streams 对互操作性起着重要作用。它对库和基础设施组件很有意义，但作为应用程序的API却不太有用，因为它太低级了。应用程序需要一个更高级别的、更丰富的、功能性的API来组成异步逻辑—​类似于Java 8的 Stream API，但不只是用于集合。这就是响应式库所扮演的角色。

Reactor 是Spring WebFlux 的首选响应式库。它提供了 Mono 和 Flux API类型，通过与 ReactiveX 运算符词汇 相一致的丰富运算符集，对 0..1（Mono）和 0..N（Flux）的数据序列进行操作。Reactor是一个Reactive Streams库，因此，它的所有操作符都支持非阻塞的背压。Reactor非常关注服务器端的Java。它是与Spring紧密合作开发的。

WebFlux需要Reactor作为核心依赖，但它可以通过Reactive Streams与其他响应式库互操作。一般来说，WebFlux API接受一个普通的 Publisher 作为输入，在内部将其调整为Reactor类型，使用该类型，并返回 Flux 或 Mono 作为输出。因此，你可以传递任何 Publisher 作为输入，你可以在输出上应用操作，但你需要调整输出，以便与另一个响应式库一起使用。在可行的情况下（例如，注解 controller），WebFlux会透明地适应RxJava或其他响应式库的使用。更多细节请参见 响应式库。

spring-web 模块包含了支撑Spring WebFlux的响应式基础，包括HTTP抽象、支持服务器的Reactive Streams 适配器、编解码器，以及与Servlet API相当但具有非阻塞约定的核心 WebHandler API。

在此基础上，Spring WebFlux提供了两种编程模型的选择：

Spring MVC 还是 WebFlux？

这是一个很自然的问题，但它却设置了一个不健全的二分法。实际上，两者都是为了扩大可用选项的范围而共同工作。两者的设计都是为了彼此的连续性和一致性，它们可以并排使用，每一方的反馈都对双方有利。下图显示了这两者的关系，它们的共同点，以及各自支持的独特之处：

我们建议你考虑以下具体要点：

Spring WebFlux支持Tomcat、Jetty、Servlet容器，以及Netty和Undertow等非Servlet运行时。所有的服务器都适应于低级别的 通用API，这样就可以跨服务器支持更高级别的 编程模型。

Spring WebFlux没有内置的支持来启动或停止服务器。然而，通过Spring配置和 WebFlux基础架构 组装 一个应用程序，并通过几行代码来 运行它 是很容易的。

Spring Boot 有一个 WebFlux starter，可以自动完成这些步骤。默认情况下，starter 使用Netty，但通过改变Maven或Gradle的依赖，可以轻松切换到Tomcat、Jetty或Undertow。Spring Boot默认使用Netty，因为它在异步、非阻塞空间中使用得更广泛，可以让客户端和服务器共享资源。

Tomcat和Jetty都可以与Spring MVC和WebFlux一起使用。然而，请记住，它们的使用方式是非常不同的。Spring MVC依赖于Servlet阻塞式I/O，并让应用程序在需要时直接使用Servlet API。Spring WebFlux依赖于Servlet的非阻塞I/O，并在一个低级别的适配器后面使用Servlet API。它没有被暴露出来以供直接使用。

对于 Undertow，Spring WebFlux 直接使用 Undertow 的API，而不使用 Servlet API。

性能有很多特点和含义。响应式和非阻塞式通常不会使应用程序运行得更快。在某些情况下，它们可以（例如，如果使用 WebClient 来并行运行远程调用）。总的来说，用非阻塞的方式做事需要更多的工作，这可能会稍微增加所需的处理时间。

响应式和非阻塞式的关键预期好处是能够用少量的、固定的线程和较少的内存来扩展。这使得应用程序在负载下更有弹性，因为它们以一种更可预测的方式扩展。然而，为了观察这些好处，你需要有一些延迟（包括缓慢和不可预测的网络I/O的混合）。这就是 reactive stack 开始显示其优势的地方，其差异可能是巨大的。

Spring MVC和Spring WebFlux都支持注解 Controller ，但在并发模型以及阻塞和线程的默认假设方面有一个关键区别。

在Spring MVC（以及一般的servlet应用程序）中，假定应用程序可以阻塞当前线程，（例如，用于远程调用）。出于这个原因，servlet容器使用一个大的线程池来吸收请求处理过程中可能出现的阻塞。

在Spring WebFlux（以及一般的非阻塞服务器）中，假定应用程序不会阻塞。因此，非阻塞服务器使用一个小的、固定大小的线程池（event loop worke）来处理请求。

HttpHandler 是一个简单的契约，有一个处理请求和响应的单一方法。它有意做到最小，它的主要和唯一的目的是成为不同的HTTP服务器API的最小抽象。

下表描述了支持的服务器API：

下表描述了服务器的依赖（也见 支持的版本）：

下面的代码片段显示了在每个服务器API中使用 HttpHandler 适配器（adapter）：

Reactor Netty

Undertow

Tomcat

Jetty

Servlet 容器

要以WAR的形式部署到任何Servlet容器，你可以继承并在WAR中包含 AbstractReactiveWebInitializer。该类用 ServletHttpHandlerAdapter 包装了一个 HttpHandler，并将其注册为一个 Servlet。

org.springframework.web.server 包建立在 HttpHandler 契约的基础上，提供了一个通用的Web API，通过多个 WebExceptionHandler、多个 WebFilter 以及单个 WebHandler组件的链来处理请求。该链可以通过简单地指向 自动检测 组件的 Spring ApplicationContext，和/或通过向 builder 注册组件来与 WebHttpHandlerBuilder 组合。

虽然 HttpHandler 有一个简单的目标，即抽象出不同的HTTP服务器的使用，但 WebHandler API的目标是提供一套更广泛的在Web应用程序中常用的功能，如：

参见 Servlet 技术栈中的相应内容

在 WebHandler API, 中，你可以使用 WebFilter 在过滤器和目标 WebHandler 的其他处理链之前和之后应用拦截式逻辑。当使用 WebFlux 配置 时，注册一个 WebFilter 就像把它声明为一个Spring Bean一样简单，并（可选择）通过在bean声明中使用 @Order 或实现 Ordered 来表达优先级。

参见 Servlet 技术栈中的相应内容

在 WebHandler API 中，你可以使用一个 WebExceptionHandler 来处理来自 WebFilter 实例链和目标 WebHandler 的异常。当使用 WebFlux 配置 时，注册一个 WebExceptionHandler 就像把它声明为 Spring Bean 一样简单，并（可选择）通过在bean声明中使用 @Order 或实现 Ordered 来表达优先级。

下表描述了可用的 WebExceptionHandler 实现：

参见 Servlet 技术栈中的相应内容

spring-web 和 spring-core 模块通过非阻塞I/O与Reactive Streams背压，提供了对高层对象的字节内容序列化和反序列化的支持。下面描述了这种支持：

spring-core 模块提供 byte[]、ByteBuffer、DataBuffer、Resource 和 String 编码器和解码器的实现。spring-web 模块提供了 Jackson JSON、Jackson Smile、JAXB2、Protocol Buffers 和其他编码器和解码器，以及针对表单数据、multipart 内容、server-sent event 和其他的web专用HTTP消息读写器实现。

ClientCodecConfigurer and ServerCodecConfigurer are typically used to configure and customize the codecs to use in an application. See the section on configuring HTTP消息编解码器.

ClientCodecConfigurer 和 ServerCodecConfigurer 通常被用来配置和定制应用中使用的编解码器。参见配置 HTTP消息编解码器 的章节。

参见 Servlet 技术栈中的相应内容

Spring WebFlux中的 DEBUG 级别日志被设计成紧凑、简约和人性化的。它专注于高价值的信息，这些信息可以反复使用，而其他信息只有在调试某个特定问题时才会有用。

TRACE 级别的日志通常遵循与 DEBUG 相同的原则（例如也不应该是火线），但可以用于调试任何问题。此外，一些日志信息在 TRACE 与 DEBUG 下可能显示不同的细节。

好的日志来自于使用日志的经验。如果你发现任何不符合既定目标的地方，请让我们知道。

参见 Servlet 技术栈中的相应内容

DispatcherHandler 委托给特殊的Bean来处理请求并呈现适当的响应。我们所说的 "特殊bean" 是指实现WebFlux框架契约的Spring管理的 Object 实例。这些实例通常有内置的契约，但你可以定制它们的属性，扩展它们，或替换它们。

下表列出了由 DispatcherHandler 检测的特殊 Bean。请注意，还有一些在较低级别检测到的 bean（见 特殊的 Bean 类型 中的特殊的 bean 类型）。

参见 Servlet 技术栈中的相应内容

应用程序可以声明处理请求所需的基础设施Bean（列在 Web Handler API 和 DispatcherHandler 下）。然而，在大多数情况下， WebFlux 配置 是最好的起点。它声明了所需的 Bean，并提供了一个更高层次的配置回调API来定制它。

参见 Servlet 技术栈中的相应内容

DispatcherHandler 处理请求的情况如下：

通过 HandlerAdapter 调用 handler 的返回值被包装成 HandlerResult，连同一些额外的 context，并传递给声称支持它的第一个 HandlerResultHandler。下表显示了可用的 HandlerResultHandler 实现，所有这些都在 WebFlux 配置 中声明：

参见 Servlet 技术栈中的相应内容

HandlerAdapter 的实现可以在内部处理调用 request handler 的异常，例如 controller 方法。然而，如果 request handler 返回一个异步值，那么异常可以被推迟。

HandlerAdapter 可以把它的异常处理机制公开为它返回的 HandlerResult 上设置的 DispatchExceptionHandler。当它被设置后，DispatcherHandler 也将把它应用于对结果的处理。

HandlerAdapter 也可以选择实现 DispatchExceptionHandler。在这种情况下， DispatcherHandler 将把它应用于 handler 被映射之前出现的异常，例如在 handler 映射过程中，或者更早，例如在一个 WebFilter 中。

请参阅 "注解 controller" 部分的 异常（Exception） 或 WebHandler API 部分的 异常（Exception） 。

参见 Servlet 技术栈中的相应内容

视图解析能够通过HTML模板和模型向浏览器进行渲染，而不需要将你束缚在特定的视图技术上。在Spring WebFlux 中，视图解析是通过一个专门的 HandlerResultHandler 来支持的，该 Handler 使用 ViewResolver 实例将一个字符串（代表逻辑视图名称）映射到一个 View 实例。然后，该 View 被用来渲染响应。

参见 Servlet 技术栈中的相应内容

你可以通过使用标准的 Spring Bean 定义来定义 Controller Bean。@Controller stereotype 允许自动检测，并与 Spring 对检测 classpath 中的 @Component 类和为其自动注册Bean定义的一般支持保持一致。它也是注解类的一个 stereotype，表明它是一个 web 组件。

为了实现对这种 @Controller Bean的自动检测，你可以在你的Java配置中添加组件扫描，如下例所示：

@RestController 是一个 组成的注解，它本身是由 @Controller 和 @ResponseBody 组成的元注解，表示一个 controller 的每个方法都继承了类型级的 @ResponseBody 注解，因此，直接写到响应体，而不是用HTML模板进行视图解析和渲染。

参见 Servlet 技术栈中的相应内容

@RequestMapping 注解用于将请求映射到 controller 方法。它有各种属性，可以通过URL、HTTP方法、请求参数、header 和媒体类型进行匹配。你可以在类的层面上使用它来表达共享映射，也可以在方法的层面上使用它来缩小到一个特定的端点映射。

还有 HTTP 方法特定的 @RequestMapping 的快捷方式变体：

前面的注解是 自定义注解，因为可以说，大多数 controller 方法应该被映射到特定的HTTP方法，而不是使用 @RequestMapping，默认情况下，它与所有HTTP方法相匹配。同时，在类的层面上仍然需要一个 @RequestMapping 来表达共享映射。

下面的例子使用了类型和方法级别的映射：

参见 Servlet 技术栈中的相应内容

@RequestMapping handler method 有一个灵活的签名，可以从一系列支持的 controller 方法参数和返回值中选择。

参见 Servlet 技术栈中的相应内容

你可以使用 @ModelAttribute 注解：

本节讨论 @ModelAttribute 方法，即前面列表中的第二项。一个 controller 可以有任意数量的 @ModelAttribute 方法。所有这些方法都在同一个 controller 的 @RequestMapping 方法之前被调用。一个 @ModelAttribute 方法也可以通过 @ControllerAdvice 在各个 controller 之间共享。更多细节请看 Controller Advice 部分。

@ModelAttribute 方法有灵活的方法签名。它们支持许多与 @RequestMapping 方法相同的参数（除了 @ModelAttribute 本身和与请求体有关的任何东西）。

下面的例子使用了一个 @ModelAttribute 方法：

下面的例子只添加了一个属性：

与Spring MVC不同，Spring WebFlux 明确支持模型中的响应式类型（例如，Mono<Account> 或 io.reactivex.Single<Account>）。这样的异步模型属性可以在 @RequestMapping 调用时被透明地解析（并更新模型）为它们的实际值，只要 @ModelAttribute 参数是在没有 wrapper 的情况下声明的，如下面的例子所示：

此外，任何具有响应式类型包装器（wrapper）的 model attributes 都会在视图渲染之前被解析为它们的实际值（并且模型被更新）。

你也可以使用 @ModelAttribute 作为 @RequestMapping 方法的方法级注解，在这种情况下，@RequestMapping 方法的返回值被解释为 model attribute。这通常是不需要的，因为它是HTML controller 中的默认行为，除非返回值是一个 String，否则会被解释为视图名称。@ModelAttribute 也可以帮助定制 model attribute 名称，正如下面的例子所示：

参见 Servlet 技术栈中的相应内容

@Controller 或 @ControllerAdvice 类可以有 @InitBinder 方法，用来初始化 WebDataBinder 的实例。这些方法反过来又被用来：

@InitBinder 方法可以注册 controller 特定的 java.beans.PropertyEditor 或 Spring Converter 和 Formatter 组件。此外，你可以使用 WebFlux Java 配置，在全局共享的 FormattingConversionService 中注册 Converter 和 Formatter 类型。

@InitBinder 方法支持许多与 @RequestMapping 方法相同的参数，除了 @ModelAttribute（命令对象）参数。通常情况下，它们被声明为有一个 WebDataBinder 参数，用于注册，以及一个 void 返回值。下面的例子使用了 @InitBinder 注解：

另外，当通过共享的 FormattingConversionService 使用基于 Formatter 的设置时，你可以重新使用相同的方法，并注册 controller 特定的 Formatter 实例，如下例所示：

参见 Servlet 技术栈中的相应内容

@Controller 和 @ControllerAdvice 类可以有 @ExceptionHandler 方法来处理 controller 方法的异常。下面的例子包含了这样一个处理方法：

异常可以与正在传播的顶层异常（即直接抛出的 IOException）相匹配，也可以与顶层封装异常中的直接原因（cause）相匹配（例如，在 IllegalStateException 中封装的 IOException）。

对于匹配的异常类型，最好将目标异常作为方法参数来声明，如前面的例子所示。另外，注解声明可以缩小要匹配的异常类型。我们一般建议在参数签名中尽可能具体，并在 @ControllerAdvice 上声明你的主要根异常映射，并以相应的顺序进行优先排序。详情见 MVC 部分。

Spring WebFlux 中对 @ExceptionHandler 方法的支持是由 @RequestMapping 方法的 HandlerAdapter 提供。更多细节请参见 DispatcherHandler。

参见 Servlet 技术栈中的相应内容

通常情况下，@ExceptionHandler、@InitBinder 和 @ModelAttribute 方法适用于它们所声明的 @Controller 类（或类的层次结构）中。如果你想让这些方法在更大范围内应用（跨 controller），你可以在一个用 @ControllerAdvice 或 @RestControllerAdvice 注解的类中声明它们。

@ControllerAdvice 是用 @Component 来注解的，这意味着这样的类可以通过 组件扫描 被注册为Spring Bean。@RestControllerAdvice 是一个由 @ControllerAdvice 和 @ResponseBody 组成的注解，这基本上意味着 @ExceptionHandler 方法会通过消息转换（相对于视图解析或模板渲染）渲染到响应体。

在启动时，@RequestMapping 和 @ExceptionHandler 方法的基础架构类会检测到用 @ControllerAdvice 注解的Spring Bean，然后在运行时应用其方法。全局性的 @ExceptionHandler 方法（来自 @ControllerAdvice）会在本地方法（来自 @Controller）之后应用。相比之下，全局的 @ModelAttribute 和 @InitBinder 方法会在本地方法之前应用。

默认情况下，@ControllerAdvice 方法适用于每一个请求（也就是所有的 controller），但你可以通过在注解上使用属性，将范围缩小到 controller 的一个子集，如下例所示：

前面例子中的选择器（selectors）是在运行时评估的，如果大量使用可能会对性能产生负面影响。更多细节请参见 @ControllerAdvice javadoc。

参见 Servlet 栈中的相应内容

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

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

RouterFunctions.route() 提供了一个 router builder，便于创建 router，如下例所示：

运行 RouterFunction 的一个方法是把它变成一个 HttpHandler，并通过一个内置的 server adapter 来安装它：

大多数应用程序可以通过 WebFlux Java 配置运行，见 运行一个服务器。

参见 Servlet 栈中的相应内容

ServerRequest 和 ServerResponse 是不可变的接口，提供了JDK 8对HTTP请求（request）和响应（response）的友好访问。请求和响应都提供了 Reactive Streams 对 body 流的背压。请求 body 用Reactor Flux 或 Mono 表示。响应体用任何 Reactive Streams Publisher 表示，包括 Flux 和 Mono。关于这一点，请看 Reactive Libraries。

参见 Servlet 栈中的相应内容

Router 函数被用来将请求路由到相应的 HandlerFunction。通常情况下，你不会自己编写 router 函数，而是使用 RouterFunctions 工具类的方法来创建一个。RouterFunctions.route() （无参数） 为你提供了一个创建 router 函数的 fluent builder，而 RouterFunctions.route(RequestPredicate, HandlerFunction) 提供了一个创建 router 的直接方法。

一般来说，建议使用 route() builder，因为它为典型的映射场景提供了方便的捷径，而不需要难以发现的静态导入。例如，路由函数生成器提供了 GET(String, HandlerFunction) 方法，用于创建 GET 请求的映射；POST(String, HandlerFunction) 用于POST。

除了基于HTTP方法的映射，route builder 还提供了一种方法，在映射到请求时引入额外的 predicate。每个HTTP方法都有一个重载的变体，它以 RequestPredicate 为参数，尽管它可以表达额外的约束。

参见 Servlet 栈中的相应内容

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

然后，你可以通过遵循 HttpHandler 对服务器的特定说明，将返回的 HttpHandler 用于一些 server adapter。

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

前面的组件让函数式端点适配 DispatcherHandler 请求处理的生命周期，并且与注解的 controller（如果有的话）并排运行。这也是Spring Boot WebFlux starter 启用函数式端点的方式。

下面的例子显示了一个 WebFlux 的 Java 配置（关于如何运行它，请看 DispatcherHandler）：

参见 Servlet 栈中的相应内容

你可以通过使用 router function builder 上的 before、after 或 filter 方法来过滤 handler 函数。通过注解，你可以通过使用 @ControllerAdvice、ServletFilter 或两者实现类似的功能。该过滤器将应用于由 builder 构建的所有路由。这意味着在嵌套路由中定义的过滤器并不适用于 "顶层" 路由。例如，考虑下面的例子：

router builder 上的 filter 方法接受一个 HandlerFilterFunction：一个接受 ServerRequest 和 HandlerFunction 并返回 ServerResponse 的函数。handler 函数参数代表链中的下一个元素。这通常是被路由到的 handler，但如果应用多个过滤器，它也可以是另一个过滤器。

现在我们可以给我们的路由添加一个简单的 security 过滤器（filter），假设我们有一个 SecurityManager，可以决定是否允许某个特定路径。下面的例子显示了如何做到这一点：

前面的例子表明，调用 next.handle(ServerRequest) 是可选的。我们只让 handler 函数在访问被允许时运行。

除了在 router function builder 上使用 filter 方法，还可以通过 RouterFunction.filter(HandlerFilterFunction) 将过滤器应用于现有的 router 函数。

Spring MVC 和 Spring WebFlux

UriComponentsBuilder 有助于从带有变量的URI模板中建立URI，如下例所示：

前面的例子可以合并成链式调用，并用 buildAndExpand 来缩短，如下图所示：

你可以通过直接进入URI（这意味着编码）来进一步缩短它，如下例所示：

你还可以用一个完整的URI模板进一步缩短它，如下例所示：

Spring MVC 和 Spring WebFlux

UriComponentsBuilder 实现了 UriBuilder。你可以反过来用 UriBuilderFactory 创建一个 UriBuilder。UriBuilderFactory 和 UriBuilder 一起提供了一个可插拔的机制，根据共享的配置，如 base URL、编码偏好和其他细节，从URI模板中构建URI。

你可以用一个 UriBuilderFactory 来配置 RestTemplate 和 WebClient，以定制URI的准备。 DefaultUriBuilderFactory 是 UriBuilderFactory 的默认实现，它在内部使用 UriComponentsBuilder 并公开共享配置选项。

下面的例子显示了如何配置一个 RestTemplate：

下面的例子配置了一个 WebClient：

此外，你也可以直接使用 DefaultUriBuilderFactory。它类似于使用 UriComponentsBuilder，但是，它不是静态的工厂方法，而是一个实际的实例，持有配置和偏好，如下例所示：

Spring MVC 和 Spring WebFlux

UriComponentsBuilder 在两个层面上暴露了编码（encoding）选项：

这两个选项都是用转义的八进制替换非ASCII和非法字符。然而，第一个选项也替换了URI变量中出现的具有保留意义的字符。

在大多数情况下，第一个选项可能会得到预期的结果，因为它将URI变量作为不透明的数据进行完全编码，而第二个选项在URI变量有意包含保留字符时非常有用。第二个选项在完全不展开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。

参见 Servlet 栈中的相应内容

出于安全考虑，浏览器禁止AJAX调用当前来源以外的资源。例如，你可以将你的银行账户放在一个 tab 中，而将 evil.com 放在另一个 tab 中。evil.com 的脚本不应该能够用你的凭证向您的银行API发出AJAX请求—​例如，从你的账户中取钱

跨域资源共享（CORS）是由 大多数浏览器 实施的 W3C规范，它让你指定哪种跨域请求被授权，而不是使用基于IFRAME或JSONP的不太安全和不太强大的变通方法。

参见 Servlet 栈中的相应内容

CORS规范区分了预检、简单和实际请求。要了解CORS是如何工作的，你可以阅读 这篇文章，以及其他许多文章，或者查看规范以了解更多细节。

Spring WebFlux HandlerMapping 的实现提供了对CORS的内置支持。在成功地将一个请求映射到一个 handler 后，HandlerMapping 会检查给定请求和 handler 的CORS配置，并采取进一步行动。预检请求被直接处理，而简单和实际的CORS请求被拦截、验证，并设置所需的CORS响应头。

为了启用跨域请求（即 Origin 头存在，并且与请求的主机不同），你需要有一些明确声明的CORS配置。如果没有找到匹配的 CORS 配置，预检请求将被拒绝。在简单和实际的 CORS 请求的响应中没有添加 CORS 头，因此，浏览器会拒绝它们。

每个 HandlerMapping 都可以 配置 单独使用基于 URL pattern 的 CorsConfiguration 映射。在大多数情况下，应用程序使用 WebFlux 的 Java 配置来声明这种映射，这导致一个单一的、全局的映射传递给所有 HandlerMapping 实现。

你可以将 HandlerMapping 级别的全局 CORS 配置与更精细的、handler 级别的 CORS 配置相结合。例如，有注解的 controller 可以使用类或方法级的 @CrossOrigin 注解（其他 handler 可以实现 CorsConfigurationSource）。

结合全局和本地配置的规则通常是相加的—​例如，所有全局和所有本地的 origin。对于那些只能接受一个值的属性，例如 allowCredentials 和 maxAge，本地的要优先于全局的值。参见 CorsConfiguration#combine(CorsConfiguration) 了解更多细节。

参见 Servlet 栈中的相应内容

@CrossOrigin 注解可以对注解的 controller 方法进行跨域请求，如下图所示：

默认情况下，@CrossOrigin 允许：

allowCredentials 默认不启用，因为这建立了一个信任级别，暴露了敏感的用户特定信息（如cookies和CSRF令牌），应该只在适当的时候使用。当它被启用时，必须将 allowOrigins 设置为一个或多个特定的域（但不是特殊值 "*"），或者可以使用 allowOriginPatterns 属性来匹配一组动态的 origin。

maxAge 被设置为30分钟。

@CrossOrigin 在类的层面上也被支持，并被所有方法继承。下面的例子指定了一个特定的域，并将 maxAge 设置为一个小时：

你可以在类和方法层面上使用 @CrossOrigin，如下例所示：

参见 Servlet 栈中的相应内容

除了细粒度的 controller 方法级配置外，你可能也想定义一些全局的 CORS 配置。你可以在任何 HandlerMapping 上单独设置基于 URL 的 CorsConfiguration 映射。然而，大多数应用程序使用 WebFlux 的 Java 配置来做到这一点。

在默认情况下，全局配置会启用以下功能：

allowedCredentials 默认不启用，因为它建立了一个信任级别，暴露了敏感的用户特定信息（如cookies和CSRF令牌），应该只在适当的地方使用。当它被启用时，allowOrigins 必须被设置为一个或多个特定的域（但不是特殊值 "*"），或者可以使用 allowOriginPatterns 属性来匹配一组动态的 origin。

maxAge 被设置为30分钟。

要在 WebFlux Java 配置中启用 CORS，你可以使用 CorsRegistry 回调，如下例所示：

参见 Servlet 栈中的相应内容

你可以通过内置的 CorsWebFilter 来应用CORS支持，这与 函数式端点 很契合。

为了配置过滤器（filter），你可以声明一个 CorsWebFilter Bean，并将一个 CorsConfigurationSource 传递给它的构造函数，如下例所示：

参见 Servlet 技术栈中的相应内容

你可以从任何 @ExceptionHandler 或任何 @RequestMapping 方法中返回 ProblemDetail 或 ErrorResponse，以呈现 RFC 7807 响应。这将被处理如下：

要启用RFC7807对Spring WebFlux异常和任何 ErrorResponseException 的响应，请继承 ResponseEntityExceptionHandler，并在Spring配置中把它声明为 @ControllerAdvice 。该 handler 有一个 @ExceptionHandler 方法，可以处理任何 ErrorResponse 异常，其中包括所有内置的Web异常。你可以添加更多的异常处理方法，并使用一个 protected 方法将任何异常映射到 ProblemDetail。

参见 Servlet 技术栈中的相应内容

你可以通过以下两种方式之一用非标准字段扩展RFC 7807响应。

其一，插入到 ProblemDetail 的 "properties" Map 中。当使用Jackson库时，Spring框架注册了 ProblemDetailJacksonMixin，确保这个 "properties" Map 被解包并在响应中呈现为顶级的JSON属性，同样，在反序列化过程中任何未知的属性都会被插入这个 Map 中。

你也可以继承 ProblemDetail 来添加专用的非标准属性。ProblemDetail 中的 copy constructor 允许子类使其很容易从现有的 ProblemDetail 中创建。这可以集中进行，例如从一个 @ControllerAdvice，如 ResponseEntityExceptionHandler，它将一个异常的 ProblemDetail 重新创建为一个具有额外非标准字段的子类。

参见 Servlet 技术栈中的相应内容

将错误响应细节国际化是一个常见的要求，为Spring WebFlux异常定制问题细节也是一个好的做法。这方面的支持情况如下：

默认情况下，"detail" 字段的消息代码（message code）是 "problemDetail" + 全路径的的异常类名称。有些异常可能会暴露出额外的消息代码，在这种情况下，会在默认的消息代码上添加一个后缀。下表列出了Spring WebFlux异常的消息参数和代码：

默认情况下，"title" 字段的信息代码是 "problemDetail.title." + 全路径的异常类名称。

参见 Servlet 技术栈中的相应内容

客户端应用程序可以在使用 WebClient 时捕获 WebClientResponseException，或在使用 RestTemplate 时捕获 RestClientResponseException，并使用它们的 getResponseBodyAs 方法将错误响应体解码为任何目标类型，如 ProblemDetail，或 ProblemDetail 的子类。

参见 Servlet 技术栈中的相应内容

CacheControl 提供了对配置与 Cache-Control 头相关的设置的支持，并在很多地方被作为参数接受：

虽然 While RFC 7234 描述了 Cache-Control 响应头的所有可能的指令，但 CacheControl 类型采取了面向使用情况的方法，着重于常见的情况，如下例所示：

参见 Servlet 技术栈中的相应内容

Controller 可以增加对HTTP缓存的明确支持。我们推荐这样做，因为资源的 lastModified 或 ETag 值在与条件请求头进行比较之前需要计算。controller 可以为 ResponseEntity 添加 ETag 和 Cache-Control 设置，如下例所示：

如果与条件请求头的比较表明内容没有改变，前面的例子会发送一个304（NOT_MODIFIED）响应，并带有一个空的 body。否则，ETag 和 Cache-Control 头信息将被添加到响应中。

你也可以根据 controller 中的条件请求头进行检查，如下例所示：

有三种变体用于根据 eTag 值、lastModified 值或两者检查条件性请求。对于有条件的 GET 和 HEAD 请求，你可以将响应设置为304（NOT_MODIFIED）。对于有条件的 POST、PUT 和 DELETE 请求，你可以将响应设置为412（PRECONDITION_FAILED）以防止并发修改。

参见 Servlet 技术栈中的相应内容

你应该用 Cache-Control 和有条件的响应头来服务静态资源，以获得最佳性能。请参阅配置 静态资源 的章节。

参见 Servlet 栈中的相应内容

Thymeleaf 是一个现代的服务器端Java模板引擎，它强调自然的HTML模板，可以通过双击在浏览器中预览，这对于独立的UI模板工作非常有帮助（例如，由设计师来完成），而不需要运行服务器。Thymeleaf提供了一套广泛的功能，而且它正在积极开发和维护。如需更完整的介绍，请参阅 Thymeleaf 项目主页。

Thymeleaf与Spring WebFlux的集成是由Thymeleaf项目管理的。该配置涉及一些bean声明，如 SpringResourceTemplateResolver、SpringWebFluxTemplateEngine 和 ThymeleafReactiveViewResolver。更多细节请参见 Thymeleaf+Spring 和WebFlux集成 公告。

参见 Servlet 栈中的相应内容

Apache FreeMarker 是一个模板引擎，用于生成从HTML到电子邮件和其他任何类型的文本输出。Spring框架有内置的集成，可以将Spring WebFlux与FreeMarker模板一起使用。

参见 Servlet 栈中的相应内容

Spring框架有一个内置的集成，可以将Spring WebFlux与任何可以在 JSR-223 Java脚本引擎之上运行的模板库进行集成。下表显示了我们在不同脚本引擎上测试的模板库：

参见 Servlet 栈中的相应内容

s对 内容协商 的目的，能够根据客户端请求的 content type，交替以HTML模板或其他格式（如JSON或XML）呈现模型是非常有用的。为了支持这样做，Spring WebFlux 提供了 HttpMessageWriterView，你可以用它来插入 spring-web 的任何可用的 编解码器（Codecs），例如 Jackson2JsonEncoder、Jackson2SmileEncoder 或 Jaxb2XmlEncoder。

与其他视图技术不同，HttpMessageWriterView 不需要 ViewResolver，而是被 配置 为一个默认视图。你可以配置一个或多个这样的默认视图，包裹不同的 HttpMessageWriter 实例或 Encoder 实例。在运行时使用与请求的 content type 相匹配的那个。

在大多数情况下，一个 model 包含多个属性。为了确定哪一个要被序列化，你可以用 model attribute 的名称来配置 HttpMessageWriterView，以便用于渲染。如果 model 只包含一个属性，则使用该属性。

参见 Servlet 技术栈中的相应内容

你可以在你的Java配置中使用 @EnableWebFlux 注解，如下例所示：

前面的例子注册了一些 Spring WebFlux 基础设施 Bean，并适配classpath上可用的依赖—​用于JSON、XML和其他。

参见 Servlet 技术栈中的相应内容

在你的Java配置中，你可以实现 WebFluxConfigurer 接口，如下例所示：

参见 Servlet 技术栈中的相应内容

默认情况下，各种 number 和 date 类型的 formatter 已被安装，同时还支持通过字段上的 @NumberFormat 和 @DateTimeFormat 进行定制。

要在 Java config 中注册自定义 formatter 和 converter，请使用以下方法：

默认情况下，Spring WebFlux 在解析和格式化 date 值时考虑请求的 Locale。这适用于日期被表示为字符串的 "input" 表单字段。然而，对于 "date" 和 "time" 表单字段，浏览器使用HTML规范中定义的固定格式。在这种情况下，date 和 time 的格式化可以按以下方式定制：

参见 Servlet 技术栈中的相应内容

默认情况下，如果在 classpath 上存在 Bean Validation（例如 Hibernate Validator），LocalValidatorFactoryBean 就会被注册为全局验证器，以便在 @Controller 方法参数上使用 @Valid 和 @Validated。

在你的 Java 配置中，你可以自定义全局 Validator 实例，如下例所示：

注意，你也可以在本地注册 Validator 实现，如下例所示：

参见 Servlet 技术栈中的相应内容

你可以配置 Spring WebFlux 如何从请求中确定 @Controller 实例的请求媒体类型。默认情况下，只检查 Accept 头，但你也可以启用基于查询参数的策略。

下面的例子显示了如何定制所请求的 content type 解析：

参见 Servlet 技术栈中的相应内容

下面的例子显示了如何定制请求和响应体的读写方式：

ServerCodecConfigurer 提供了一套默认的 reader 和 writer。你可以用它来添加更多的 reader 和 writer，自定义默认的 reader 和 writer，或者完全替换默认的 reader 和 writer。

对于 Jackson 的 JSON 和 XML，可以考虑使用 Jackson2ObjectMapperBuilder，它用以下属性定制了Jackson的默认属性：

如果在 classpath 上检测到以下知名模块，它也会自动注册这些模块：

参见 Servlet 技术栈中的相应内容

下面的例子显示了如何配置视图解析：

ViewResolverRegistry 有与Spring框架集成的视图技术的快捷方式。下面的例子使用了FreeMarker（这也需要配置基础的FreeMarker视图技术）：

你也可以插入任何 ViewResolver 实现，如下例所示：

为了支持 内容协商 和通过视图解析渲染其他格式（除了HTML），你可以在 HttpMessageWriterView 实现的基础上配置一个或多个默认视图，它接受 spring-web 中任何可用的 编解码器（Codecs）。下面的例子展示了如何做到这一点：

关于与Spring WebFlux集成的视图技术的更多信息，请参阅 视图技术 。

参见 Servlet 技术栈中的相应内容

这个选项提供了一个方便的方法，从基于 Resource 的位置列表中提供静态资源。

在下一个例子中，给定一个以 /resources 开头的请求，相对路径被用来寻找和提供相对于 classpath 上的 /static 的静态资源。提供的资源将在未来一年内到期，以确保最大限度地利用浏览器的缓存，并减少浏览器的HTTP请求。Last-Modified 头也会被评估，如果存在，会返回 304 状态代码。下面的列表显示了这个例子：

另见 HTTP 对静态资源的缓存支持。

资源处理程序还支持 ResourceResolver 实现和 ResourceTransformer 实现的链，它们可以被用来创建一个处理优化资源的工具链。

你可以使用 VersionResourceResolver 来获取基于从内容计算的MD5哈希值、固定的应用程序版本或其他信息的版本资源URL。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是通过 WebJarsResourceResolver 支持的，当 org.webjars:webjars-locator-core 库出现在classpath上时，它就会自动注册，代价是classpath扫描会减慢应用程序的启动。该解析器可以重写URL以包括jar的版本，也可以与传入的没有版本的URL相匹配—​例如，从 /webjars/jquery/jquery.min.js 到 /webjars/jquery/1.2.0/jquery.min.js。

参见 Servlet 技术栈中的相应内容

你可以自定义与路径匹配有关的选项。关于各个选项的细节，请参见 PathMatchConfigurer javadoc。下面的例子展示了如何使用 PathMatchConfigurer：

WebFlux的Java配置声明了一个 WebSocketHandlerAdapter Bean，它为 WebSocket handler 的调用提供支持。这意味着为了处理 WebSocket 握手请求，所要做的就是通过 SimpleUrlHandlerMapping 将 WebSocketHandler 映射到一个URL。

在某些情况下，可能需要通过提供的 WebSocketService 服务来创建 WebSocketHandlerAdapter Bean，该 service 允许配置 WebSocket 服务器属性。例如：

参见 Servlet 技术栈中的相应内容

@EnableWebFlux 导入 DelegatingWebFluxConfiguration：

对于高级模式，你可以删除 @EnableWebFlux，直接从 DelegatingWebFluxConfiguration 中继承，而不是实现 WebFluxConfigurer，如下图所示：

你可以保留 WebConfig 中现有的方法，但你现在也可以覆盖基类中的bean声明，并且在classpath上仍然有任何数量的其他 WebMvcConfigurer 实现。

编解码器有在内存中缓冲数据的 限制，以避免应用程序的内存问题。默认情况下，这些限制被设置为256KB。如果这还不够，你会得到以下错误：

要改变默认编解码器的限制，使用以下方法：

为了定制Reactor Netty设置，提供一个预配置的 HttpClient：

下面的例子显示了如何定制 JDK HttpClient：

下面的例子显示了如何定制 Jetty HttpClient 设置：

默认情况下，HttpClient 创建了它自己的资源（Executor、ByteBufferPool、Scheduler），这些资源一直处于活动状态，直到进程退出或 stop() 被调用。

你可以在多个Jetty客户端（和服务器）实例之间共享资源，并通过声明一个 JettyResourceFactory 类型的Spring管理的Bean来确保资源在Spring ApplicationContext 关闭时被关闭，如下图所示：

下面的例子显示了如何定制Apache HttpComponents HttpClient 设置：

为了发送表单数据，你可以提供一个 MultiValueMap<String, String> 作为 body。注意，内容被 FormHttpMessageWriter 自动设置为 application/x-www-form-urlencoded。下面的例子显示了如何使用 MultiValueMap<String, String>：

你也可以通过使用 BodyInserters 内联提供表单数据，如下例所示：

为了发送 multipart data，你需要提供一个 MultiValueMap<String, ?>，其值要么是代表 part 内容的 Object 实例，要么是代表一个 part 的 content 和 header 的 HttpEntity 实例。MultipartBodyBuilder 提供了一个方便的API来准备一个 multipart 请求。下面的例子显示了如何创建一个 MultiValueMap<String, ?>：

在大多数情况下，你不需要为每个 part 指定 Content-Type。content type 是根据为序列化它而选择的 HttpMessageWriter 自动确定的，或者在 Resource 的情况下，根据文件扩展名确定。如果有必要，你可以通过重载的 builder part 方法之一明确地提供用于每个 part 的 MediaType 。

一旦准备好 MultiValueMap，将其传递给 WebClient 的最简单的方法是通过 body 方法，正如下面的例子所示：

如果 MultiValueMap 至少包含一个非 String 值，它也可以代表常规的表单数据（即 application/x-www-form-urlencoded），你不需要将内容类型设置为 multipart/form-data。在使用 MultipartBodyBuilder 时总是这样，它确保了一个 HttpEntity wrapper。

作为 MultipartBodyBuilder 的替代方案，你也可以通过内置的 BodyInserters 提供 multipart content，以内联方式进行，如下例所示：