Spring WebFlux 官方文档

2. Spring WebClient

3. Spring Websocket

本文由 简悦 SimpRead 转码， 原文地址 docs.spring.io

其余参考：spring-framework 5.1.3 中文文档 - Spring WebFlux

Spring WebFlux Version 5.3.14

This part of the documentation covers support for reactive-stack web applications built on a Reactive Streams API to run on non-blocking servers, such as Netty, Undertow, and Servlet 3.1+ containers. Individual chapters cover the Spring WebFlux framework, the reactive WebClient, support for testing, and reactive libraries. For Servlet-stack web applications, see Web on Servlet Stack.

文档的这一部分涵盖了对基于Reactive Streams API构建的反应堆栈 Web 应用程序的支持，以在非阻塞服务器上运行，例如 Netty、Undertow 和 Servlet 3.1+ 容器。各个章节涵盖了Spring WebFlux框架、反应式WebClient、测试支持和反应式库。对于 Servlet 堆栈 Web 应用程序，请参阅Servlet 堆栈上的 Web。

1. Spring WebFlux

The original web framework included in the Spring Framework, Spring Web MVC, was purpose-built for the Servlet API and Servlet containers. The reactive-stack web framework, Spring WebFlux, was added later in version 5.0. It is fully non-blocking, supports Reactive Streams back pressure, and runs on such servers as Netty, Undertow, and Servlet 3.1+ containers.

Spring Framework 中包含的原始 Web 框架 Spring Web MVC 是专门为 Servlet API 和 Servlet 容器构建的。响应式堆栈 Web 框架 Spring WebFlux 是在 5.0 版本中添加的。它是完全非阻塞的，支持 Reactive Streams背压，并在 Netty、Undertow 和 Servlet 3.1+ 容器等服务器上运行。

Both web frameworks mirror the names of their source modules (spring-webmvc and spring-webflux) and co-exist side by side in the Spring Framework. Each module is optional. Applications can use one or the other module or, in some cases, both — for example, Spring MVC controllers with the reactive WebClient.

两个 Web 框架都反映了它们的源模块（spring-webmvc和 spring-webflux）的名称，并在 Spring 框架中并排共存。每个模块都是可选的。应用程序可以使用一个或另一个模块，或者在某些情况下，两者都使用——例如，带有响应式WebClient.

1.1. Overview 【概述】

Why was Spring WebFlux created?

Part of the answer is the need for a non-blocking web stack to handle concurrency with a small number of threads and scale with fewer hardware resources. Servlet 3.1 did provide an API for non-blocking I/O. However, using it leads away from the rest of the Servlet API, where contracts are synchronous (Filter, Servlet) or blocking (getParameter, getPart). This was the motivation for a new common API to serve as a foundation across any non-blocking runtime. That is important because of servers (such as Netty) that are well-established in the async, non-blocking space.

部分原因是需要一个非阻塞的 Web 堆栈来处理并发，使用少量线程，并能够使用较少的硬件资源进行扩展。Servlet 3.1 确实为非阻塞 I/O 提供了 API。但是，使用它会导致偏离 Servlet API 的其余部分，那些本身是同步 ( Filter, Servlet) 或阻塞 ( getParameter, getPart)操作的API。这就是将新的通用 API 用作任何非阻塞运行时的基础的动机。这很重要，因为服务器（例如 Netty）在异步、非阻塞领域中运行地很好。

The other part of the answer is functional programming. Much as the addition of annotations in Java 5 created opportunities (such as annotated REST controllers or unit tests), the addition of lambda expressions in Java 8 created opportunities for functional APIs in Java. This is a boon for non-blocking applications and continuation-style APIs (as popularized by CompletableFuture and ReactiveX) that allow declarative composition of asynchronous logic. At the programming-model level, Java 8 enabled Spring WebFlux to offer functional web endpoints alongside annotated controllers.

另一部分原因是函数式编程。就像在 Java 5 中添加注解创造了机会（例如带注解的 REST 控制器或单元测试）一样，在 Java 8 中添加 lambda 表达式为 Java 中的函数式 API 创造了机会。这对于允许异步逻辑的声明式组​​合的非阻塞应用程序和延续式 API（由CompletableFuture和ReactiveX推广）是一个福音。在编程模型级别，Java 8 使 Spring WebFlux 能够配合注解控制器提供函数式 Web 端点。

1.1.1. Define “Reactive” 【定义“反应性”】

We touched on “non-blocking” and “functional” but what does reactive mean?

我们谈到了“非阻塞”和“功能性”，但是反应式是什么意思呢？ 关于反应式介绍可参考此篇文章，建议看

The term, “reactive,” refers to programming models that are built around reacting to change — network components reacting to I/O events, UI controllers reacting to mouse events, and others. In that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode of reacting to notifications as operations complete or data becomes available.

术语“反应性”指的是围绕对变化做出反应而构建的编程模型——网络组件对 I/O 事件做出反应，UI 控制器对鼠标事件做出反应，等等。从这个意义上说，非阻塞是反应性的，因为我们现在处于对通知作出反应的模式，而不是被阻塞，因为操作完成或数据可用。

There is also another important mechanism that we on the Spring team associate with “reactive” and that is non-blocking back pressure. In synchronous, imperative code, blocking calls serve as a natural form of back pressure that forces the caller to wait. In non-blocking code, it becomes important to control the rate of events so that a fast producer does not overwhelm its destination.

还有另一个重要的机制，我们在 Spring 团队中与“反应性”相关联，那就是非阻塞背压。在同步的命令式代码中，阻塞调用是一种自然的背压形式，迫使调用者等待。在非阻塞代码中，控制事件发生率使得快速生产者不会压倒其目的地变得很重要。(注：背压解释参见此文章种解释)

Reactive Streams is a small spec (also adopted in Java 9) that defines the interaction between asynchronous components with back pressure. For example a data repository (acting as Publisher) can produce data that an HTTP server (acting as Subscriber) can then write to the response. The main purpose of Reactive Streams is to let the subscriber control how quickly or how slowly the publisher produces data.

Reactive Streams 是一个 小规范 （也在Java 9 中采用 也可见此文章：JDK9 Reactive部分），它定义了带有背压的异步组件之间的交互。例如，数据存储库（充当 Publisher）可以生成 HTTP 服务器（充当 Subscriber）然后可以写入响应的数据。Reactive Streams 的主要目的是让订阅者控制发布者生成数据的速度或速度。

  Common question: what if a publisher cannot slow down?
  The purpose of Reactive Streams is only to establish the mechanism and a boundary. If a publisher cannot slow down, it has to decide whether to buffer, drop, or fail.

常见问题：如果发布者不能放慢发布速度怎么办？
Reactive Streams 的目的只是建立机制和边界。如果发布者不能放慢速度，它就必须决定是缓冲、丢弃还是失败。

1.1.2. Reactive API

Reactive Streams plays an important role for interoperability. It is of interest to libraries and infrastructure components but less useful as an application API, because it is too low-level. Applications need a higher-level and richer, functional API to compose async logic — similar to the Java 8 Stream API but not only for collections. This is the role that reactive libraries play.

Reactive Streams 在互操作性方面发挥着重要作用。它对库和基础设施组件很感兴趣，但作为应用程序 API 不太有用，因为它太低级了。应用程序需要一个更高级、更丰富的功能性 API 来组合异步逻辑——类似于 Java 8 StreamAPI，但不仅限于集合。这就是反应式库所扮演的角色。

Reactor is the reactive library of choice for Spring WebFlux. It provides the Mono and Flux API types to work on data sequences of 0..1 (Mono) and 0..N (Flux) through a rich set of operators aligned with the ReactiveX vocabulary of operators. Reactor is a Reactive Streams library and, therefore, all of its operators support non-blocking back pressure. Reactor has a strong focus on server-side Java. It is developed in close collaboration with Spring.

Reactor是 Spring WebFlux 的首选反应库。它提供了 Mono和 FluxAPI 类型，以通过一组丰富的与 ReactiveX运算符词汇表对齐的运算符来处理 0..1个数据( Mono) 和 0..N个数据( Flux) 的数据序列。Reactor 是一个 Reactive Streams 库，因此它的所有操作符都支持非阻塞背压。Reactor 非常关注服务器端 Java。它是与 Spring 密切合作开发的。

WebFlux requires Reactor as a core dependency but it is interoperable with other reactive libraries via Reactive Streams. As a general rule, a WebFlux API accepts a plain Publisher as input, adapts it to a Reactor type internally, uses that, and returns either a Flux or a Mono as output. So, you can pass any Publisher as input and you can apply operations on the output, but you need to adapt the output for use with another reactive library. Whenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use of RxJava or another reactive library. See Reactive Libraries for more details.

WebFlux 需要 Reactor 作为核心依赖项，但它可以通过 Reactive Streams 与其他反应式库互操作。作为一般规则，WebFlux API 接受一个普通的Publisher 作为输入，在内部将其调整为 Reactor 类型，使用它，并返回 a Flux或 aMono作为输出。因此，您可以将任何Publisher作为输入传递，并且可以对输出应用操作，但是您需要调整输出以与另一个反应式库一起使用。只要可行（例如，带注解的控制器），WebFlux 就会透明地适应 RxJava 或其他反应式库的使用。有关更多详细信息，请参阅反应库。

In addition to Reactive APIs, WebFlux can also be used with coroutines APIs in Kotlin which provides a more imperative style of programming. The following Kotlin code samples will be provided with Coroutines APIs.

除了 Reactive API 之外，WebFlux 还可以与Kotlin 中的Coroutines API一起使用， 这提供了更加命令式的编程风格。以下 Kotlin 代码示例将与 Coroutines API 一起提供。

1.1.3. Programming Models 【编程模型】

The spring-web module contains the reactive foundation that underlies Spring WebFlux, including HTTP abstractions, Reactive Streams adapters for supported servers, codecs, and a core WebHandler API comparable to the Servlet API but with non-blocking contracts.

spring-web模块包含了反应式的基本功能框架(在Spring WebFlux之中)，包括 HTTP 抽象、用于支持各种服务器的反应式流适配器、编解码器以及与 Servlet API 相当但具有非阻塞特性的核心WebHandlerAPI。(注：此处及之后的服务器应指Tomcat、Netty等服务器技术程序)

On that foundation, Spring WebFlux provides a choice of two programming models:

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

• Annotated Controllers: Consistent with Spring MVC and based on the same annotations from the spring-web module. Both Spring MVC and WebFlux controllers support reactive (Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable difference is that WebFlux also supports reactive @RequestBody arguments.

• 带注解的控制器：与 Spring MVC 一致并基于spring-web模块中的相同注解。Spring MVC 和 WebFlux 控制器都支持反应式（Reactor 和 RxJava）返回类型，因此，很难区分它们。一个显着的区别是 WebFlux 还支持响应式@RequestBody参数。

• Functional Endpoints: Lambda-based, lightweight, and functional programming model. You can think of this as a small library or a set of utilities that an application can use to route and handle requests. The big difference with annotated controllers is that the application is in charge of request handling from start to finish versus declaring intent through annotations and being called back.

• 函数式端点：基于 Lambda 的轻量级函数式编程模型。您可以将其视为应用程序可用于路由和处理请求的小型库或一组实用程序。与带注解的控制器的最大区别在于，应用程序负责从头到尾的请求处理，而不是通过注解声明意图并被回调。

1.1.4. Applicability 【适用性】

Spring MVC or WebFlux?

Spring MVC 还是 WebFlux？

A natural question to ask but one that sets up an unsound dichotomy. Actually, both work together to expand the range of available options. The two are designed for continuity and consistency with each other, they are available side by side, and feedback from each side benefits both sides. The following diagram shows how the two relate, what they have in common, and what each supports uniquely:

一个很自然的问题，但会造成不合理的二分法。实际上，两者协同工作扩大了可选项的范围。两者的设计都是为了彼此的连续性和一致性，它们可以一起使用，来自任一方的反馈对双方都有好处。下图显示了两者之间的关系、它们的共同点以及各自独特的支持：

We suggest that you consider the following specific points:

我们建议您考虑以下具体问题：

• If you have a Spring MVC application that works fine, there is no need to change. Imperative programming is the easiest way to write, understand, and debug code. You have maximum choice of libraries, since, historically, most are blocking.

• 如果您有一个运行良好的 Spring MVC 应用程序，则无需更改。命令式编程是编写、理解和调试代码的最简单方法。你有最多的库选择，因为从历史上看，大多数都是阻塞的。

• If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same execution model benefits as others in this space and also provides a choice of servers (Netty, Tomcat, Jetty, Undertow, and Servlet 3.1+ containers) , a choice of programming models (annotated controllers and functional web endpoints), and a choice of reactive libraries (Reactor, RxJava, or other).

• 如果您已经准备购买非阻塞 Web 堆栈，Spring WebFlux 提供与该领域中的其他技术相同的执行模型优势，并且还提供各种服务器技术选项（Netty、Tomcat、Jetty、Undertow 和 Servlet 3.1+ 容器）、多种编程模式选项（带注解的controllers或是函数式编程的 Web 端点），以及多种反应式技术库选项（Reactor、RxJava 或其他）。

• If you are interested in a lightweight, functional web framework for use with Java 8 lambdas or Kotlin, you can use the Spring WebFlux functional web endpoints. That can also be a good choice for smaller applications or microservices with less complex requirements that can benefit from greater transparency and control.

• 如果您对使用 Java 8 lambdas 或 Kotlin 的轻量级函数式编程 Web 框架感兴趣，可以使用 Spring WebFlux 函数式编程 Web 端点。对于较小的应用程序或具有不太复杂的要求的微服务，这也是一个不错的选择，可以从更高的透明度和控制中受益。

• In a microservice architecture, you can have a mix of applications with either Spring MVC or Spring WebFlux controllers or with Spring WebFlux functional endpoints. Having support for the same annotation-based programming model in both frameworks makes it easier to re-use knowledge while also selecting the right tool for the right job.

• 在微服务架构中，您可以混合使用 Spring MVC 或 Spring WebFlux controllers或 Spring WebFlux 函数式编程端点的应用程序。在两个框架中都支持相同的基于注解的编程模型，可以更轻松地重用知识，同时还可以为正确的工作选择正确的工具。

• A simple way to evaluate an application is to check its dependencies. If you have blocking persistence APIs (JPA, JDBC) or networking APIs to use, Spring MVC is the best choice for common architectures at least. It is technically feasible with both Reactor and RxJava to perform blocking calls on a separate thread but you would not be making the most of a non-blocking web stack.

• 评估应用程序的一种简单方法是检查其依赖。如果您已有阻塞持久性 API（JPA、JDBC）或网络 API 可供使用，那么Spring MVC 至少是通用架构的最佳选择。虽然Reactor 和 RxJava 在单独的线程上执行阻塞调用在技术上是可行的，但您没办法充分利用其非阻塞 Web 堆栈。

• If you have a Spring MVC application with calls to remote services, try the reactive WebClient. You can return reactive types (Reactor, RxJava, or other) directly from Spring MVC controller methods. The greater the latency per call or the interdependency among calls, the more dramatic the benefits. Spring MVC controllers can call other reactive components too.

• 如果您有一个调用远程服务的 Spring MVC 应用程序，请尝试响应式WebClient. 您可以直接从 Spring MVC 控制器方法返回反应式类型（Reactor、RxJava或其他）。每个调用的延迟或调用之间的相互依赖性越大，好处就越大。Spring MVC 控制器也可以调用其他反应式组件。

• If you have a large team, keep in mind the steep learning curve in the shift to non-blocking, functional, and declarative programming. A practical way to start without a full switch is to use the reactive WebClient. Beyond that, start small and measure the benefits. We expect that, for a wide range of applications, the shift is unnecessary. If you are unsure what benefits to look for, start by learning about how non-blocking I/O works (for example, concurrency on single-threaded Node.js) and its effects.

• 如果您有一个大型团队，请注意向非阻塞、函数式和声明式编程转变的陡峭学习曲线。在未完成技术转型的情况下一种实用的转型起步方式是使用反应式WebClient作为开端。除此之外，从小处着手并衡量收益。我们预计，对于大多数的应用程序，这种技术转型是不必要的。如果您不确定要从此技术上得到什么好处，请首先了解非阻塞 I/O 的工作原理（例如，单线程 Node.js 上的并发）及其影响。

1.1.5. Servers 【服务器】

Spring WebFlux is supported on Tomcat, Jetty, Servlet 3.1+ containers, as well as on non-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level, common API so that higher-level programming models can be supported across servers >.

Spring WebFlux 支持 Tomcat、Jetty、Servlet 3.1+ 容器以及non-Servlet 运行时环境（如 Netty 和 Undertow）。所有服务器都适用低级的 通用 API，以便更高级别的 编程模型能够在跨服务器下也能获得支持。(注：此处及之后的服务器应指Tomcat、Netty等服务器技术程序)

Spring WebFlux does not have built-in support to start or stop a server. However, it is easy to assemble an application from Spring configuration and WebFlux infrastructure and run it with a few lines of code.

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

Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses Netty, but it is easy to switch to Tomcat, Jetty, or Undertow by changing your Maven or Gradle dependencies. Spring Boot defaults to Netty, because it is more widely used in the asynchronous, non-blocking space and lets a client and a server share resources.

Spring Boot 有一个 WebFlux 启动器可以自动执行这些步骤。默认情况下，启动器使用 Netty，但通过更改 Maven 或 Gradle 依赖项，可以轻松切换到 Tomcat、Jetty 或 Undertow。Spring Boot 默认使用 Netty，因为它更广泛地用于异步、非阻塞空间，让客户端和服务器共享资源（注：此应该是指使用webclient发送请求和启动的对外提供服务的服务器底层都使用的netty，然后netty底层线程等资源可以共享？见）。

Tomcat and Jetty can be used with both Spring MVC and WebFlux. Keep in mind, however, that the way they are used is very different. Spring MVC relies on Servlet blocking I/O and lets applications use the Servlet API directly if they need to. Spring WebFlux relies on Servlet 3.1 non-blocking I/O and uses the Servlet API behind a low-level adapter. It is not exposed for direct use.

Tomcat 和 Jetty 都可以 Spring MVC 或 WebFlux 一起使用。但是请记住，它们的使用方式是非常不同的。Spring MVC 依赖于 Servlet 阻塞 I/O，并让应用程序在需要时直接使用 Servlet API。Spring WebFlux 依赖于 Servlet 3.1 非阻塞 I/O，并通过低级适配器来使用 Servlet API。它并不直接暴露Servlet API来供直接使用。

For Undertow, Spring WebFlux uses Undertow APIs directly without the Servlet API.

对于 Undertow，Spring WebFlux 直接使用 Undertow API，没有 Servlet API。

1.1.6. Performance 【性能】

Performance has many characteristics and meanings. Reactive and non-blocking generally do not make applications run faster. They can, in some cases, (for example, if using the WebClient to run remote calls in parallel). On the whole, it requires more work to do things the non-blocking way and that can slightly increase the required processing time.

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

The key expected benefit of reactive and non-blocking is the ability to scale with a small, fixed number of threads and less memory. That makes applications more resilient under load, because they scale in a more predictable way. In order to observe those benefits, however, you need to have some latency (including a mix of slow and unpredictable network I/O). That is where the reactive stack begins to show its strengths, and the differences can be dramatic.

反应式和非阻塞式的主要可预见的好处是能够使用少量固定数量的线程和更少的内存进行扩展。这使得应用程序的负载更具弹性，因为它们以更可预测的方式扩展。然而，当您的程序本身有一些延迟（包括缓慢和不可预测的网络 I/O ）的时候，才能体现这些好处。这就是反应式技术栈开始显示其优势的地方，并且差异可能是巨大的。

1.1.7. Concurrency Model 【并发模型】

Both Spring MVC and Spring WebFlux support annotated controllers, but there is a key difference in the concurrency model and the default assumptions for blocking and threads.

Spring MVC 和 Spring WebFlux 都支持带注解的控制器，但在并发模型及阻塞和线程的默认假设上有一个关键的区别。

In Spring MVC (and servlet applications in general), it is assumed that applications can block the current thread, (for example, for remote calls). For this reason, servlet containers use a large thread pool to absorb potential blocking during request handling.

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

In Spring WebFlux (and non-blocking servers in general), it is assumed that applications do not block. Therefore, non-blocking servers use a small, fixed-size thread pool (event loop workers) to handle requests.

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

“To scale” and “small number of threads” may sound contradictory but to never block the current thread (and rely on callbacks instead) means that you do not need extra threads, as there are no blocking calls to absorb.

“扩展”和“少量线程”可能听起来很矛盾，但从不阻塞当前线程（而是依靠回调）意味着您不需要额外的线程，因为没有阻塞调用需要吸收。

Invoking a Blocking API
调用阻塞 API

What if you do need to use a blocking library? Both Reactor and RxJava provide the publishOn operator to continue processing on a different thread. That means there is an easy escape hatch. Keep in mind, however, that blocking APIs are not a good fit for this concurrency model.

如果确实需要使用阻塞库怎么办？Reactor 和 RxJava 都提供了publishOn操作符以在不同线程上继续处理见。这意味着有一个简单的逃生舱口。但是请记住，阻塞 API 并不适合这种并发模型。

Mutable State
可变状态

In Reactor and RxJava, you declare logic through operators. At runtime, a reactive pipeline is formed where data is processed sequentially, in distinct stages. A key benefit of this is that it frees applications from having to protect mutable state because application code within that pipeline is never invoked concurrently.

在 Reactor 和 RxJava 中，您通过运算符声明逻辑。在运行时，会形成一个反应式管道，其中数据在不同的阶段按顺序进行处理。这样做的一个关键好处是它使应用程序不必保护可变状态，因为该管道中的应用程序代码永远不会被并发调用。

Threading Model
线程模型

What threads should you expect to see on a server running with Spring WebFlux?

您希望在运行 Spring WebFlux 的服务器上看到哪些线程？

• On a “vanilla” Spring WebFlux server (for example, no data access nor other optional dependencies), you can expect one thread for the server and several others for request processing (typically as many as the number of CPU cores). Servlet containers, however, may start with more threads (for example, 10 on Tomcat), in support of both servlet (blocking) I/O and servlet 3.1 (non-blocking) I/O usage.

• 在“普通”的 Spring WebFlux 服务器上（例如，没有数据访问或其他可选的依赖项），你可以使用一个线程用于服务器，几个线程用于请求处理（通常与 CPU 内核的数量一样多）。然而，Servlet 容器可能以更多线程（例如，Tomcat 的 10 个）开始，以支持 servlet（阻塞）I/O 和 servlet 3.1（非阻塞）I/O 的使用。

• The reactive WebClient operates in event loop style. So you can see a small, fixed number of processing threads related to that (for example, reactor-http-nio- with the Reactor Netty connector). However, if Reactor Netty is used for both client and server, the two share event loop resources by default.

• 反应式WebClient式以事件循环的形式运行。因此，您可以看到仅少量固定数量的处理线程与此相关的（例如，reactor-http-nio-使用 Reactor Netty connector）。但是，如果客户端和服务器都使用 Reactor Netty，则默认情况下两者共享事件循环资源。

• Reactor and RxJava provide thread pool abstractions, called schedulers, to use with the publishOn operator that is used to switch processing to a different thread pool. The schedulers have names that suggest a specific concurrency strategy — for example, “parallel” (for CPU-bound work with a limited number of threads) or “elastic” (for I/O-bound work with a large number of threads). If you see such threads, it means some code is using a specific thread pool Scheduler strategy.

• Reactor 和 RxJava 提供线程池抽象，叫做调度者，与publishOn 操作符一起用于将实际处理切换到不同线程池 。调度者的具体实现的类的名称暗示了特定的并发策略——例如，“并行”（用于有限数量线程的 CPU 密集型工作）或“弹性”（用于具有大量线程的 I/O 密集型工作）。如果您看到此类线程，则表示某些代码正在使用特定的线程池Scheduler策略。

• Data access libraries and other third party dependencies can also create and use threads of their own.

• 数据访问相关的类库或其他第三方依赖项也可以创建和使用它们自己的线程。

Configuring
配置

The Spring Framework does not provide support for starting and stopping servers. To configure the threading model for a server, you need to use server-specific configuration APIs, or, if you use Spring Boot, check the Spring Boot configuration options for each server. You can configure the WebClient directly. For all other libraries, see their respective documentation.

Spring Framework 本身并不对 服务器的启动和停止提供支持。要为服务器配置线程模型，您需要使用对应服务器的配置 API，或者，如果您使用 Spring Boot，请检查每个服务器的 Spring Boot 配置选项。您可以 直接配置的WebClient。对于其他库，请参阅它们各自的文档。(注：此处的服务器指tomcat、netty等服务器技术栈或对应的服务器)

1.2. Reactive Core

The spring-web module contains the following foundational support for reactive web applications:

spring-web模块包含以下对反应式 Web 应用程序的基础支持：

• For server request processing there are two levels of support.

• 对于服务器请求处理，有两个级别的支持。

  • HttpHandler: Basic contract for HTTP request handling with non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, Undertow, Tomcat, Jetty, and any Servlet 3.1+ container.

  • HttpHandler：用于HTTP 请求处理的基本契约/合同/框架/API/接口，具有非阻塞 I/O 和反应流背压，以及用于 Reactor Netty、Undertow、Tomcat、Jetty 和任何 Servlet 3.1+ 容器的适配器。

  • WebHandler API: Slightly higher level, general-purpose web API for request handling, on top of which concrete programming models such as annotated controllers and functional endpoints are built.

  • WebHandlerAPI：用于请求处理的稍高级别的通用 Web API，在其之上构建了具体的编程模型，例如带注解的控制器和函数式端点。

• For the client side, there is a basic ClientHttpConnector contract to perform HTTP requests with non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, reactive Jetty HttpClient and Apache HttpComponents. The higher level WebClient used in applications builds on this basic contract.

• 对于客户端，有一个基本的ClientHttpConnector契约/接口，与用于Reactor Netty、响应式 Jetty HttpClient 和Apache HttpComponents 的适配器一起来执行具有非阻塞 I/O 和响应式流背压的 HTTP 请求 。应用程序中则使用建立在此基础上的更高级的WebClient。

• For client and server, codecs for serialization and deserialization of HTTP request and response content.

• 对于客户端和服务器，编解码器用于 HTTP 请求和响应内容的序列化和反序列化。

1.2.1. HttpHandler

HttpHandler is a simple contract with a single method to handle a request and a response. It is intentionally minimal, and its main and only purpose is to be a minimal abstraction over different HTTP server APIs.

HttpHandler 是一个简单的契约，它具有处理请求和响应的单一方法。它有意最小化，其主要和唯一目的是对不同 HTTP 服务器 API 进行最小化抽象。

The following table describes the supported server APIs:

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

Server name	Server API used	Reactive Streams support
Netty	Netty API	Reactor Netty
Undertow	Undertow API	spring-web: Undertow to Reactive Streams bridge
Tomcat	Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[]	spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
Jetty	Servlet 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[]	spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
Servlet 3.1 container	Servlet 3.1 non-blocking I/O	spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge

The following table describes server dependencies (also see supported versions):

下表描述了服务器依赖项（另请参阅 支持的版本）：

Server name	Group id	Artifact name
Reactor Netty	io.projectreactor.netty	reactor-netty
Undertow	io.undertow	undertow-core
Tomcat	org.apache.tomcat.embed	tomcat-embed-core
Jetty	org.eclipse.jetty	jetty-server, jetty-servlet

The code snippets below show using the HttpHandler adapters with each server API:

下面的代码片段显示了将HttpHandler适配器与每个服务器 API 一起使用：

Reactor Netty

HttpHandler handler = ...
ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);
HttpServer.create().host(host).port(port).handle(adapter).bind().block();

Undertow

HttpHandler handler = ...
UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler);
Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build();
server.start();

Tomcat

HttpHandler handler = ...
Servlet servlet = new TomcatHttpHandlerAdapter(handler);

Tomcat server = new Tomcat();
File base = new File(System.getProperty("java.io.tmpdir"));
Context rootContext = server.addContext("", base.getAbsolutePath());
Tomcat.addServlet(rootContext, "main", servlet);
rootContext.addServletMappingDecoded("/", "main");
server.setHost(host);
server.setPort(port);
server.start();

Jetty

HttpHandler handler = ...
Servlet servlet = new JettyHttpHandlerAdapter(handler);

Server server = new Server();
ServletContextHandler contextHandler = new ServletContextHandler(server, "");
contextHandler.addServlet(new ServletHolder(servlet), "/");
contextHandler.start();

ServerConnector connector = new ServerConnector(server);
connector.setHost(host);
connector.setPort(port);
server.addConnector(connector);
server.start();

Servlet 3.1+ Container

To deploy as a WAR to any Servlet 3.1+ container, you can extend and include AbstractReactiveWebInitializer in the WAR. That class wraps an HttpHandler with ServletHttpHandlerAdapter and registers that as a Servlet.

要将 WAR 部署到任何 Servlet 3.1+ 容器，您可以扩展并包含 AbstractReactiveWebInitializer 在 WAR 中。此类用ServletHttpHandlerAdapter适配器包装了一个HttpHandler并将其注册为一个Servlet.

1.2.2. WebHandler API

The org.springframework.web.server package builds on the HttpHandler contract to provide a general-purpose web API for processing requests through a chain of multiple WebExceptionHandler, multiple WebFilter, and a single WebHandler component. The chain can be put together with WebHttpHandlerBuilder by simply pointing to a Spring ApplicationContext where components are auto-detected, and/or by registering components with the builder.

org.springframework.web.server包构建在HttpHandler契约/框架/API/接口之上，用于提供通用的 Web API，通过包含多个WebExceptionHandler、多个 WebFilter和单个 WebHandler组件组成的链来处理请求 。可以使用WebHttpHandlerBuilder通过简单地指定能够自动检测组件 的SpringApplicationContext 和/或通过向builder注册组件来组成链。

While HttpHandler has a simple goal to abstract the use of different HTTP servers, the WebHandler API aims to provide a broader set of features commonly used in web applications such as:

虽然HttpHandler有一个简单的目标 —— 抽象不同 HTTP 服务器的使用，但 WebHandlerAPI 旨在提供更广泛的 Web 应用程序中常用的功能，例如：

• User session with attributes. 具有属性的用户会话。

• Request attributes. 请求属性。

• Resolved Locale or Principal for the request. 解决请求的Locale或Principal。

• Access to parsed and cached form data. 访问已解析和缓存的表单数据。

• Abstractions for multipart data. 抽象multipart数据。

• and more..

Special bean types

The table below lists the components that WebHttpHandlerBuilder can auto-detect in a Spring ApplicationContext, or that can be registered directly with it:

下表列出了WebHttpHandlerBuilder可以在 Spring ApplicationContext 中自动检测的组件，或者可以直接向其注册的组件：

Bean name	Bean type	Count	Description
	WebExceptionHandler	0..N	Provide handling for exceptions from the chain of WebFilter instances and the target WebHandler. For more details, see Exceptions.
	WebFilter	0..N	Apply interception style logic to before and after the rest of the filter chain and the target WebHandler. For more details, see Filters.
webHandler	WebHandler	1	The handler for the request.
webSessionManager	WebSessionManager	0..1	The manager for WebSession instances exposed through a method on ServerWebExchange. DefaultWebSessionManager by default.
serverCodecConfigurer	ServerCodecConfigurer	0..1	For access to HttpMessageReader instances for parsing form data and multipart data that is then exposed through methods on ServerWebExchange. ServerCodecConfigurer.create() by default.
localeContextResolver	LocaleContextResolver	0..1	The resolver for LocaleContext exposed through a method on ServerWebExchange. AcceptHeaderLocaleContextResolver by default.
forwardedHeaderTransformer	ForwardedHeaderTransformer	0..1	For processing forwarded type headers, either by extracting and removing them or by removing them only. Not used by default.

Form Data 【表单数据】

ServerWebExchange exposes the following method for accessing form data:

ServerWebExchange 暴露以下访问表单数据的方法：

Mono<MultiValueMap<String, String>> getFormData();

The DefaultServerWebExchange uses the configured HttpMessageReader to parse form data (application/x-www-form-urlencoded) into a MultiValueMap. By default, FormHttpMessageReader is configured for use by the ServerCodecConfigurer bean (see the Web Handler API).

DefaultServerWebExchange使用配置的HttpMessageReader解析表单数据（application/x-www-form-urlencoded）成为一个MultiValueMap。默认情况下， FormHttpMessageReader配置为供ServerCodecConfigurer类使用（请参阅Web 处理程序 API）。

Multipart Data

ServerWebExchange exposes the following method for accessing multipart data:

ServerWebExchange暴露以下用于访问multipart数据的方法：

Mono<MultiValueMap<String, Part>> getMultipartData();

The DefaultServerWebExchange uses the configured HttpMessageReader<MultiValueMap<String, Part>> to parse multipart/form-data content into a MultiValueMap. By default, this is the DefaultPartHttpMessageReader, which does not have any third-party dependencies. Alternatively, the SynchronossPartHttpMessageReader can be used, which is based on the Synchronoss NIO Multipart library. Both are configured through the ServerCodecConfigurer bean (see the Web Handler API).

DefaultServerWebExchange使用配置的 HttpMessageReader<MultiValueMap<String, Part>>解析multipart/form-data内容成MultiValueMap。默认情况下，这是DefaultPartHttpMessageReader，它没有任何第三方依赖项。或者，SynchronossPartHttpMessageReader可以使用基于 Synchronoss NIO Multipart库的 。两者都是通过ServerCodecConfigurerbean配置的（请参阅Web Handler API）。

To parse multipart data in streaming fashion, you can use the Flux<Part> returned from an HttpMessageReader<Part> instead. For example, in an annotated controller, use of @RequestPart implies Map-like access to individual parts by name and, hence, requires parsing multipart data in full. By contrast, you can use @RequestBody to decode the content to Flux<Part> without collecting to a MultiValueMap.

要以流式方式解析多部分数据，您可以改用从Flux<Part>返回的 HttpMessageReader<Part>。例如，在一个带注解的控制器中，使用类似于按名称访问各个部分的 @RequestPart隐含方式Map，因此需要完整解析多部分数据。相比之下，您可以使用@RequestBody将内容解码为 ，Flux<Part>而无需收集到MultiValueMap.

As a request goes through proxies (such as load balancers), the host, port, and scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct host, port, and scheme.

当请求通过代理（例如负载均衡器）时，主机、端口和方案可能会发生变化。从客户端的角度来看，这使得创建指向正确主机、端口和方案的链接成为一项挑战。

RFC 7239 defines the Forwarded HTTP header that proxies can use to provide information about the original request. There are other non-standard headers, too, including X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Ssl, and X-Forwarded-Prefix.

RFC 7239定义了Forwarded代理可以用来提供有关原始请求的信息的HTTP 标头。还有其他一些非标头，也包括X-Forwarded-Host，X-Forwarded-Port， X-Forwarded-Proto，X-Forwarded-Ssl，和X-Forwarded-Prefix。

ForwardedHeaderTransformer is a component that modifies the host, port, and scheme of the request, based on forwarded headers, and then removes those headers. If you declare it as a bean with the name forwardedHeaderTransformer, it will be detected and used.

ForwardedHeaderTransformer是一个组件，它根据转发的标头修改请求的主机、端口和方案，然后删除这些标头。如果您将其声明为名称为 的 bean forwardedHeaderTransformer，它将被 检测到并使用。

There are security considerations for forwarded headers, since an application cannot know if the headers were added by a proxy, as intended, or by a malicious client. This is why a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming from the outside. You can also configure the ForwardedHeaderTransformer with removeOnly=true, in which case it removes but does not use the headers.

转发标头存在安全考虑，因为应用程序无法知道标头是由代理添加的、按预期添加的，还是由恶意客户端添加的。这就是为什么应该配置信任边界处的代理以删除来自外部的不受信任的转发流量。您还可以配置ForwardedHeaderTransformerwith removeOnly=true，在这种情况下它会删除但不使用标头。

In 5.1 ForwardedHeaderFilter was deprecated and superceded by ForwardedHeaderTransformer so forwarded headers can be processed earlier, before the exchange is created. If the filter is configured anyway, it is taken out of the list of filters, and ForwardedHeaderTransformer is used instead.

在 5.1 中 ForwardedHeaderFilter被弃用和取代， ForwardedHeaderTransformer因此可以在创建交换之前更早地处理转发的标头。如果无论如何都配置了过滤器，则会将其从过滤器列表中取出并ForwardedHeaderTransformer改为使用。

1.2.3. Filters 【过滤器】

In the WebHandler API, you can use a WebFilter to apply interception-style logic before and after the rest of the processing chain of filters and the target WebHandler. When using the WebFlux Config, registering a WebFilter is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using @Order on the bean declaration or by implementing Ordered.

在WebHandlerAPI 中，您可以使用 aWebFilter在过滤器和目标的其余处理链之前和之后应用拦截式逻辑 WebHandler。使用WebFlux Config 时，注册 aWebFilter就像将其声明为 Spring bean 和（可选）通过@Order在 bean 声明上使用或通过实现Ordered.

CORS

Spring WebFlux provides fine-grained support for CORS configuration through annotations on controllers. However, when you use it with Spring Security, we advise relying on the built-in CorsFilter, which must be ordered ahead of Spring Security’s chain of filters.

Spring WebFlux 通过控制器上的注解为 CORS 配置提供细粒度的支持。但是，当您将它与 Spring Security 一起使用时，我们建议依靠内置的 CorsFilter，它必须在 Spring Security 的过滤器链之前订购。

1.2.4. Exceptions 【异常】

In the WebHandler API, you can use a WebExceptionHandler to handle exceptions from the chain of WebFilter instances and the target WebHandler. When using the WebFlux Config, registering a WebExceptionHandler is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using @Order on the bean declaration or by implementing Ordered.

在WebHandlerAPI 中，您可以使用 aWebExceptionHandler来处理来自WebFilter实例链和目标的异常WebHandler。使用 WebFlux Config 时，注册 aWebExceptionHandler就像将其声明为 Spring bean 和（可选）通过@Order在 bean 声明上使用或通过实现Ordered.

The following table describes the available WebExceptionHandler implementations:

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

Exception Handler	Description
ResponseStatusExceptionHandler	Provides handling for exceptions of type ResponseStatusException by setting the response to the HTTP status code of the exception.
WebFluxResponseStatusExceptionHandler	Extension of ResponseStatusExceptionHandler that can also determine the HTTP status code of a @ResponseStatus annotation on any exception. This handler is declared in the WebFlux Config.

Exception Handler	Description
ResponseStatusExceptionHandler	ResponseStatusException 通过设置对异常的 HTTP 状态代码的响应来提供对类型异常的处理 。
WebFluxResponseStatusExceptionHandler	其扩展ResponseStatusExceptionHandler还可以确定@ResponseStatus任何异常注解的 HTTP 状态代码。 此处理程序在WebFlux Config 中声明。

1.2.5. Codecs 【编解码器】

The spring-web and spring-core modules provide support for serializing and deserializing byte content to and from higher level objects through non-blocking I/O with Reactive Streams back pressure. The following describes this support:

spring-web和spring-core模块通过与反应性流背压非阻塞I / O用于序列化和反序列化字节内容和从更高级别的对象提供支持。下面描述了这种支持：

• Encoder and Decoder are low level contracts to encode and decode content independent of HTTP.

• Encoder并且 Decoder是独立于 HTTP 对内容进行编码和解码的低级合同。

• HttpMessageReader and HttpMessageWriter are contracts to encode and decode HTTP message content.

• HttpMessageReader并且 HttpMessageWriter是对 HTTP 消息内容进行编码和解码的合约。

• An Encoder can be wrapped with EncoderHttpMessageWriter to adapt it for use in a web application, while a Decoder can be wrapped with DecoderHttpMessageReader.

• 一个Encoder可以用 包装以EncoderHttpMessageWriter使其适应在 Web 应用程序中使用，而 aDecoder可以用 包装DecoderHttpMessageReader。

• DataBuffer abstracts different byte buffer representations (e.g. Netty ByteBuf, java.nio.ByteBuffer, etc.) and is what all codecs work on. See Data Buffers and Codecs in the "Spring Core" section for more on this topic.

• DataBuffer抽象不同的字节缓冲区表示（例如 Netty ByteBuf、java.nio.ByteBuffer等），这是所有编解码器的工作。有关此主题的更多信息，请参阅“Spring Core”部分中的数据缓冲区和编解码器。

The spring-core module provides byte[], ByteBuffer, DataBuffer, Resource, and String encoder and decoder implementations. The spring-web module provides Jackson JSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders along with web-only HTTP message reader and writer implementations for form data, multipart content, server-sent events, and others.

spring-core模块提供byte[]、ByteBuffer、DataBuffer、Resource和 String编码器和解码器实现。该spring-web模块提供 Jackson JSON、Jackson Smile、JAXB2、Protocol Buffers 和其他编码器和解码器，以及用于表单数据、多部分内容、服务器发送事件等的纯 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 message codecs.

ClientCodecConfigurer并且ServerCodecConfigurer通常用于配置和自定义要在应用程序中使用的编解码器。请参阅有关配置HTTP 消息编解码器的部分 。

Jackson JSON

JSON and binary JSON (Smile) are both supported when the Jackson library is present.

当 Jackson 库存在时，JSON 和二进制 JSON ( Smile ) 都受支持。

The Jackson2Decoder works as follows:

Jackson2Decoder解码器工作原理如下：

• Jackson’s asynchronous, non-blocking parser is used to aggregate a stream of byte chunks into TokenBuffer's each representing a JSON object.

• Jackson 的异步、非阻塞解析器用于将字节块流聚合到TokenBuffer's 每个代表一个 JSON 对象。

• Each TokenBuffer is passed to Jackson’s ObjectMapper to create a higher level object.

• 每个TokenBuffer都传递给 JacksonObjectMapper以创建更高级别的对象。

• When decoding to a single-value publisher (e.g. Mono), there is one TokenBuffer.

• 当解码到单值发布者（例如Mono）时，有一个TokenBuffer.

• When decoding to a multi-value publisher (e.g. Flux), each TokenBuffer is passed to the ObjectMapper as soon as enough bytes are received for a fully formed object. The input content can be a JSON array, or any line-delimited JSON format such as NDJSON, JSON Lines, or JSON Text Sequences.

• 当解码为多值发布者（例如Flux），每个TokenBuffer被传递给ObjectMapper只要足够的字节是为完全形成的对象接收。输入内容可以是 JSON 数组，也可以是任何以 行分隔的 JSON格式，例如 NDJSON、JSON 行或 JSON 文本序列。

The Jackson2Encoder works as follows:

Jackson2Encoder编码器工作原理如下：

• For a single value publisher (e.g. Mono), simply serialize it through the ObjectMapper.

• 对于单值发布者（例如Mono），只需通过 ObjectMapper.

• For a multi-value publisher with application/json, by default collect the values with Flux#collectToList() and then serialize the resulting collection.

• 对于具有 的多值发布者application/json，默认情况下使用 收集值， Flux#collectToList()然后序列化结果集合。

• For a multi-value publisher with a streaming media type such as application/x-ndjson or application/stream+x-jackson-smile, encode, write, and flush each value individually using a line-delimited JSON format. Other streaming media types may be registered with the encoder.

• 对于具有流媒体类型（例如application/x-ndjsonor ）的多值发布者， application/stream+x-jackson-smile使用行分隔的 JSON格式单独编码、写入和刷新每个值 。其他流媒体类型可以注册到编码器。

• For SSE the Jackson2Encoder is invoked per event and the output is flushed to ensure delivery without delay.

• 对于 SSE，Jackson2Encoder每个事件都会调用它，并刷新输出以确保无延迟交付。

  By default both `Jackson2Encoder` and `Jackson2Decoder` do not support elements of type `String`. Instead the default assumption is that a string or a sequence of strings represent serialized JSON content, to be rendered by the `CharSequenceEncoder`. If what you need is to render a JSON array from `Flux<String>`, use `Flux#collectToList()` and encode a `Mono<List<String>>`.

  默认情况下，`Jackson2Encoder`和`Jackson2Decoder`都不支持`String`类型。相反，默认假设是一个字符串或一系列字符串表示序列化的 JSON 内容，由`CharSequenceEncoder`. 如果您需要从 呈现 JSON 数组`Flux<String>`，请使用`Flux#collectToList()`并编码`Mono<List<String>>`.

Form Data 【表单数据】

FormHttpMessageReader and FormHttpMessageWriter support decoding and encoding application/x-www-form-urlencoded content.

FormHttpMessageReader并FormHttpMessageWriter支持解码和编码 application/x-www-form-urlencoded内容。

On the server side where form content often needs to be accessed from multiple places, ServerWebExchange provides a dedicated getFormData() method that parses the content through FormHttpMessageReader and then caches the result for repeated access. See Form Data in the WebHandler API section.

在经常需要从多个地方访问表单内容的服务器端， ServerWebExchange提供了一个专用的getFormData()方法，通过解析内容FormHttpMessageReader然后缓存结果以供重复访问。请参阅API部分中的表单数据。[WebHandler](

Once getFormData() is used, the original raw content can no longer be read from the request body. For this reason, applications are expected to go through ServerWebExchange consistently for access to the cached form data versus reading from the raw request body.

一旦getFormData()使用，就无法再从请求正文中读取原始原始内容。出于这个原因，应用程序应该ServerWebExchange 一致地访问缓存的表单数据而不是从原始请求正文中读取。

Multipart

MultipartHttpMessageReader and MultipartHttpMessageWriter support decoding and encoding "multipart/form-data" content. In turn MultipartHttpMessageReader delegates to another HttpMessageReader for the actual parsing to a Flux<Part> and then simply collects the parts into a MultiValueMap. By default, the DefaultPartHttpMessageReader is used, but this can be changed through the ServerCodecConfigurer. For more information about the DefaultPartHttpMessageReader, refer to to the javadoc of DefaultPartHttpMessageReader.

MultipartHttpMessageReader并MultipartHttpMessageWriter支持对“multipart/form-data”内容进行解码和编码。依次MultipartHttpMessageReader委托另一个HttpMessageReader进行实际解析到 a Flux<Part>，然后简单地将部分收集到 a 中MultiValueMap。默认情况下，DefaultPartHttpMessageReader使用 ，但这可以通过 ServerCodecConfigurer. 有关 的更多信息DefaultPartHttpMessageReader，请参阅 的 javadocDefaultPartHttpMessageReader。

On the server side where multipart form content may need to be accessed from multiple places, ServerWebExchange provides a dedicated getMultipartData() method that parses the content through MultipartHttpMessageReader and then caches the result for repeated access. See Multipart Data in the WebHandler API section.

在可能需要从多处访问多部分表单内容的服务器端，ServerWebExchange提供专用getMultipartData()方法，通过解析内容MultipartHttpMessageReader然后缓存结果以供重复访问。请参阅API部分中的多部分数据。[WebHandler](

Once getMultipartData() is used, the original raw content can no longer be read from the request body. For this reason applications have to consistently use getMultipartData() for repeated, map-like access to parts, or otherwise rely on the SynchronossPartHttpMessageReader for a one-time access to Flux<Part>.

一旦getMultipartData()使用，就无法再从请求正文中读取原始原始内容。出于这个原因，应用程序必须始终如一地使用getMultipartData() 对部件的重复、类似地图的访问，或者以其他方式依赖于 SynchronossPartHttpMessageReader一次性访问Flux<Part>.

Limits 【限制】

Decoder and HttpMessageReader implementations that buffer some or all of the input stream can be configured with a limit on the maximum number of bytes to buffer in memory. In some cases buffering occurs because input is aggregated and represented as a single object — for example, a controller method with @RequestBody byte[], x-www-form-urlencoded data, and so on. Buffering can also occur with streaming, when splitting the input stream — for example, delimited text, a stream of JSON objects, and so on. For those streaming cases, the limit applies to the number of bytes associated with one object in the stream.

Decoder和HttpMessageReader该缓冲区一些或所有输入流的实施方式中可以与字节在内存中缓冲的最大数量的限制来配置。在某些情况下，会发生缓冲是因为输入被聚合并表示为单个对象——例如，带有@RequestBody byte[]、 x-www-form-urlencoded数据等的控制器方法。在拆分输入流时，流式传输也可能发生缓冲 — 例如，分隔文本、JSON 对象流等。对于那些流情况，限制适用于与流中的一个对象关联的字节数。

To configure buffer sizes, you can check if a given Decoder or HttpMessageReader exposes a maxInMemorySize property and if so the Javadoc will have details about default values. On the server side, ServerCodecConfigurer provides a single place from where to set all codecs, see HTTP message codecs. On the client side, the limit for all codecs can be changed in WebClient.Builder.

要配置缓冲区大小，您可以检查给定的Decoder或HttpMessageReader 公开的maxInMemorySize属性，如果是，Javadoc 将提供有关默认值的详细信息。在服务器端，ServerCodecConfigurer提供设置所有编解码器的单一位置，请参阅HTTP 消息编解码器。在客户端，可以在WebClient.Builder 中更改所有编解码器的限制 。

For Multipart parsing the maxInMemorySize property limits the size of non-file parts. For file parts, it determines the threshold at which the part is written to disk. For file parts written to disk, there is an additional maxDiskUsagePerPart property to limit the amount of disk space per part. There is also a maxParts property to limit the overall number of parts in a multipart request. To configure all three in WebFlux, you’ll need to supply a pre-configured instance of MultipartHttpMessageReader to ServerCodecConfigurer.

对于多部分解析该maxInMemorySize属性限制了非文件部分的大小。对于文件部分，它确定将部分写入磁盘的阈值。对于写入磁盘的文件部分，还有一个附加 maxDiskUsagePerPart属性来限制每个部分的磁盘空间量。还有一个maxParts属性可以限制多部分请求中的部分总数。要在 WebFlux 中配置所有三个，您需要提供一个预配置的MultipartHttpMessageReaderto实例 ServerCodecConfigurer。

Streaming 【流媒体】

When streaming to the HTTP response (for example, text/event-stream, application/x-ndjson), it is important to send data periodically, in order to reliably detect a disconnected client sooner rather than later. Such a send could be a comment-only, empty SSE event or any other "no-op" data that would effectively serve as a heartbeat.

当流式传输到 HTTP 响应（例如，text/event-stream, application/x-ndjson）时，定期发送数据很重要，以便尽早可靠地检测到断开连接的客户端。这样的发送可以是仅评论、空的 SSE 事件或任何其他可有效用作心跳的“无操作”数据。

DataBuffer 【数据缓冲区】

DataBuffer is the representation for a byte buffer in WebFlux. The Spring Core part of this reference has more on that in the section on Data Buffers and Codecs. The key point to understand is that on some servers like Netty, byte buffers are pooled and reference counted, and must be released when consumed to avoid memory leaks.

DataBuffer是 WebFlux 中字节缓冲区的表示。本参考的 Spring Core 部分在数据缓冲区和编解码器部分中有更多相关内容 。需要理解的关键点是，在一些像 Netty 这样的服务器上，字节缓冲区被池化和引用计数，并且必须在消耗时释放以避免内存泄漏。

WebFlux applications generally do not need to be concerned with such issues, unless they consume or produce data buffers directly, as opposed to relying on codecs to convert to and from higher level objects, or unless they choose to create custom codecs. For such cases please review the information in Data Buffers and Codecs, especially the section on Using DataBuffer.

WebFlux 应用程序通常不需要关心此类问题，除非它们直接使用或生成数据缓冲区，而不是依赖编解码器与更高级别的对象进行转换，或者除非它们选择创建自定义编解码器。对于此类情况，请查看数据缓冲区和编解码器中的信息，尤其是有关使用数据缓冲区的部分。

1.2.6. Logging 【日志】

DEBUG level logging in Spring WebFlux is designed to be compact, minimal, and human-friendly. It focuses on high value bits of information that are useful over and over again vs others that are useful only when debugging a specific issue.

DEBUGSpring WebFlux 中的级别日志被设计为紧凑、最小化和人性化。它侧重于反复有用的高价值信息与仅在调试特定问题时有用的其他信息。

TRACE level logging generally follows the same principles as DEBUG (and for example also should not be a firehose) but can be used for debugging any issue. In addition, some log messages may show a different level of detail at TRACE vs DEBUG.

TRACE级别日志记录通常遵循与DEBUG（例如也不应该是消防水管）相同的原则，但可用于调试任何问题。此外，某些日志消息可能会在TRACEvs 中显示不同级别的详细信息DEBUG。

Good logging comes from the experience of using the logs. If you spot anything that does not meet the stated goals, please let us know.

良好的日志记录来自使用日志的经验。如果您发现任何不符合既定目标的内容，请告诉我们。

Log Id 【日志编号】

In WebFlux, a single request can be run over multiple threads and the thread ID is not useful for correlating log messages that belong to a specific request. This is why WebFlux log messages are prefixed with a request-specific ID by default.

在 WebFlux 中，单个请求可以在多个线程上运行，线程 ID 对于关联属于特定请求的日志消息没有用。这就是为什么 WebFlux 日志消息默认以特定于请求的 ID 为前缀的原因。

On the server side, the log ID is stored in the ServerWebExchange attribute (LOG_ID_ATTRIBUTE), while a fully formatted prefix based on that ID is available from ServerWebExchange#getLogPrefix(). On the WebClient side, the log ID is stored in the ClientRequest attribute (LOG_ID_ATTRIBUTE) ,while a fully formatted prefix is available from ClientRequest#logPrefix().

在服务器端，日志 ID 存储在ServerWebExchange属性 ( LOG_ID_ATTRIBUTE) 中，而基于该 ID 的完全格式化的前缀可从 ServerWebExchange#getLogPrefix(). 另一方面WebClient，日志 ID 存储在 ClientRequest属性 ( LOG_ID_ATTRIBUTE) 中，而完全格式化的前缀可从ClientRequest#logPrefix().

Sensitive Data 【敏感数据】

DEBUG and TRACE logging can log sensitive information. This is why form parameters and headers are masked by default and you must explicitly enable their logging in full.

DEBUG和TRACE日志记录可以记录敏感信息。这就是默认情况下表单参数和标题被屏蔽的原因，您必须明确启用它们的完整日志记录。

The following example shows how to do so for server-side requests:

以下示例显示了如何对服务器端请求执行此操作：

@Configuration
@EnableWebFlux
class MyConfig implements WebFluxConfigurer {

    @Override
    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
        configurer.defaultCodecs().enableLoggingRequestDetails(true);
    }
}

The following example shows how to do so for client-side requests:

以下示例显示了如何对客户端请求执行此操作：

Consumer<ClientCodecConfigurer> consumer = configurer ->
        configurer.defaultCodecs().enableLoggingRequestDetails(true);

WebClient webClient = WebClient.builder()
        .exchangeStrategies(strategies -> strategies.codecs(consumer))
        .build();

Appenders

Logging libraries such as SLF4J and Log4J 2 provide asynchronous loggers that avoid blocking. While those have their own drawbacks such as potentially dropping messages that could not be queued for logging, they are the best available options currently for use in a reactive, non-blocking application.

诸如 SLF4J 和 Log4J 2 之类的日志记录库提供了避免阻塞的异步记录器。虽然这些都有其自身的缺点，例如可能会丢弃无法排队等待日志记录的消息，但它们是当前用于响应式、非阻塞应用程序的最佳可用选项。

Custom codecs 【自定义编解码器】

Applications can register custom codecs for supporting additional media types, or specific behaviors that are not supported by the default codecs.

应用程序可以注册自定义编解码器以支持其他媒体类型或默认编解码器不支持的特定行为。

Some configuration options expressed by developers are enforced on default codecs. Custom codecs might want to get a chance to align with those preferences, like enforcing buffering limits or logging sensitive data.

开发人员设置了一些配置选项在默认编解码器上强制执行。自定义编解码器可能希望有机会与这些首选项保持一致，例如强制执行缓冲限制 或记录敏感数据。

The following example shows how to do so for client-side requests:

以下示例显示了如何对客户端请求执行此操作：

WebClient webClient = WebClient.builder()
        .codecs(configurer -> {
                CustomDecoder decoder = new CustomDecoder();
                configurer.customCodecs().registerWithDefaultConfig(decoder);
        })
        .build();

1.3. DispatcherHandler 【调度处理器】

Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, where a central WebHandler, the DispatcherHandler, provides a shared algorithm for request processing, while actual work is performed by configurable, delegate components. This model is flexible and supports diverse workflows.

Spring WebFlux 与 Spring MVC 类似，是围绕前端控制器模式设计的，其中一个中央WebHandler，即DispatcherHandler，为请求处理提供共享算法，而实际工作由可配置的委托组件执行。这个模型很灵活，支持不同的工作流程。

DispatcherHandler discovers the delegate components it needs from Spring configuration. It is also designed to be a Spring bean itself and implements ApplicationContextAware for access to the context in which it runs. If DispatcherHandler is declared with a bean name of webHandler, it is, in turn, discovered by WebHttpHandlerBuilder, which puts together a request-processing chain, as described in WebHandler API.

DispatcherHandler从 Spring 配置中发现它需要的委托组件。它本身也被设计为 Spring bean，为了能够访问它运行的上下文，它还实现了ApplicationContextAware接口 。如果DispatcherHandler声明为名称为webHandler的spring bean，则它依次被WebHttpHandlerBuilder(它将请求处理链放在一起)发现，如WebHandlerAPI中所述。

Spring configuration in a WebFlux application typically contains:

WebFlux 应用程序中的 Spring 配置通常包含：

• DispatcherHandler with the bean name webHandler
• WebFilter and WebExceptionHandler beans
• DispatcherHandler special beans
• Others

The configuration is given to WebHttpHandlerBuilder to build the processing chain, as the following example shows:

配置WebHttpHandlerBuilder用于构建处理链，如下例所示：

ApplicationContext context = ...
HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build();

The resulting HttpHandler is ready for use with a server adapter.

生成的结果HttpHandler可以与服务器适配器一起使用。

1.3.1. Special Bean Types

The DispatcherHandler delegates to special beans to process requests and render the appropriate responses. By “special beans,” we mean Spring-managed Object instances that implement WebFlux framework contracts. Those usually come with built-in contracts, but you can customize their properties, extend them, or replace them.

DispatcherHandler委托特殊的类来处理请求并给出适当的响应。“特殊beans”是指Spring 管理的实现了WebFlux 框架契约/接口的Object实例。这些通常带有内置契约/接口，但您可以自定义它们的属性、扩展它们或替换它们。

The following table lists the special beans detected by the DispatcherHandler. Note that there are also some other beans detected at a lower level (see Special bean types in the Web Handler API).

下表列出了会被DispatcherHandler检测到的特殊类. 请注意，在更底层还会检测一些其他类 （请参阅 Web Handler API 中的特殊 bean 类型）。

Bean type	Explanation	说明
HandlerMapping	Map a request to a handler. The mapping is based on some criteria, the details of which vary by HandlerMapping implementation — annotated controllers, simple URL pattern mappings, and others. The main HandlerMapping implementations are RequestMappingHandlerMapping for @RequestMapping annotated methods, RouterFunctionMapping for functional endpoint routes, and SimpleUrlHandlerMapping for explicit registrations of URI path patterns and WebHandler instances.	将请求映射到对应的处理程序。映射基于一些标准，其细节因HandlerMapping实现而异——带注解的控制器、简单的 URL 模式映射，等。 主要的HandlerMapping实现有RequestMappingHandlerMapping(用于带 @RequestMapping注解的方法)、RouterFunctionMapping(用于功能端点路由)以及SimpleUrlHandlerMapping(用于URI 路径模式和WebHandler实例的显式注册)。
HandlerAdapter	Help the DispatcherHandler to invoke a handler mapped to a request regardless of how the handler is actually invoked. For example, invoking an annotated controller requires resolving annotations. The main purpose of a HandlerAdapter is to shield the DispatcherHandler from such details.	帮助DispatcherHandler调用映射到请求的处理程序，而不管处理程序实际是如何调用的。例如，调用带注解的控制器是需要解析注解的。HandlerAdapter的主要目的是保护DispatcherHandler免受这些细节的影响。
HandlerResultHandler	Process the result from the handler invocation and finalize the response. See Result Handling.	处理处理程序调用的结果并最终确定响应。请参阅结果处理。

1.3.2. WebFlux Config 【WebFlux 配置】

Applications can declare the infrastructure beans (listed under Web Handler API and DispatcherHandler) that are required to process requests. However, in most cases, the WebFlux Config is the best starting point. It declares the required beans and provides a higher-level configuration callback API to customize it.

应用程序可以声明处理请求所需的基础架构 bean（在 Web Handler API和DispatcherHandler 下列出）。然而，在大多数情况下，WebFlux Config 是最好的起点。它声明了所需的 bean 并提供了一个更高级别的配置回调 API 来自定义它。

Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides many extra convenient options.

Spring Boot 依赖于 WebFlux 配置来配置 Spring WebFlux 并且还提供了许多额外方便的选项。

1.3.3. Processing 【请求处理】

DispatcherHandler processes requests as follows:

DispatcherHandler 处理请求如下：

• Each HandlerMapping is asked to find a matching handler, and the first match is used.

• 每个HandlerMapping被要求找到一个匹配的处理程序，并使用第一个匹配项。

• If a handler is found, it is run through an appropriate HandlerAdapter, which exposes the return value from the execution as HandlerResult.

• 如果找到了一个处理程序，它会通过一个适当的HandlerAdapter(它将执行的返回值作为HandlerResult公开/暴露出来)来运行。

• The HandlerResult is given to an appropriate HandlerResultHandler to complete processing by writing to the response directly or by using a view to render.

• HandlerResult将被提供给适当的HandlerResultHandler，以便通过直接写入响应或使用视图进行渲染来完成处理。

1.3.4. Result Handling 【结果处理】

The return value from the invocation of a handler, through a HandlerAdapter, is wrapped as a HandlerResult, along with some additional context, and passed to the first HandlerResultHandler that claims support for it. The following table shows the available HandlerResultHandler implementations, all of which are declared in the WebFlux Config:

调用处理程序后的返回值通过一个HandlerAdapter包装为一个 HandlerResult，连同一些额外的上下文，传递给第一个声明支持它的 HandlerResultHandler。下表显示了可用的 HandlerResultHandler实现，所有这些都在WebFlux Config中声明：

Result Handler Type	Return Values	返回值	Default Order
ResponseEntityResultHandler	ResponseEntity, typically from @Controller instances.	ResponseEntity，通常来自被@Controller注解的实例。	0
ServerResponseResultHandler	ServerResponse, typically from functional endpoints.	ServerResponse，通常来自函数式端点。	0
ResponseBodyResultHandler	Handle return values from @ResponseBody methods or @RestController classes.	处理被@ResponseBody注解的方法或被@RestController注解的类的返回值。	100
ViewResolutionResultHandler	CharSequence, View, Model, Map, Rendering, or any other Object is treated as a model attribute. See also View Resolution.	CharSequence、View、 模型、Map、 渲染或任何其他被视为模型属性的Object。 另请参阅视图分辨率。	Integer.MAX_VALUE

1.3.5. Exceptions 【异常】

The HandlerResult returned from a HandlerAdapter can expose a function for error handling based on some handler-specific mechanism. This error function is called if:

从HandlerAdapter返回的HandlerResult可以根据特定于处理程序的机制公开/暴露用于错误处理的函数。在以下情况下会调用此错误函数：

• The handler (for example, @Controller) invocation fails.
• 处理程序（例如，@Controller）调用失败。
• The handling of the handler return value through a HandlerResultHandler fails.
• 通过HandlerResultHandler处理处理器返回值失败。

The error function can change the response (for example, to an error status), as long as an error signal occurs before the reactive type returned from the handler produces any data items.

只要在处理程序返回的反应类型产生任何数据项之前发生了错误信号，错误函数就可以更改响应（例如，更改错误状态）。

This is how @ExceptionHandler methods in @Controller classes are supported. By contrast, support for the same in Spring MVC is built on a HandlerExceptionResolver. This generally should not matter. However, keep in mind that, in WebFlux, you cannot use a @ControllerAdvice to handle exceptions that occur before a handler is chosen.

这就是@Controller注解类中@ExceptionHandler注解方法的支持方式。相比之下，Spring MVC 中对相同内容的支持是建立在HandlerExceptionResolver上的。 这通常无关紧要。但是，请记住，在 WebFlux 中，您不能使用@ControllerAdvice来处理在处理程序被选择之前就发生的异常。

1.3.6. View Resolution 【视图解析】

View resolution enables rendering to a browser with an HTML template and a model without tying you to a specific view technology. In Spring WebFlux, view resolution is supported through a dedicated HandlerResultHandler that uses ViewResolver instances to map a String (representing a logical view name) to a View instance. The View is then used to render the response.

视图解析允许使用 HTML 模板和模型渲染到浏览器，而无需绑定到特定的视图技术。在 Spring WebFlux 中，通过专用的HandlerResultHandler来支持视图解析，它使用 ViewResolver实例将一个String（代表逻辑视图名称）映射到一个View 实例。之后此View用于渲染响应。

Handling 【请求处理】

The HandlerResult passed into ViewResolutionResultHandler contains the return value from the handler and the model that contains attributes added during request handling. The return value is processed as one of the following:

传递到ViewResolutionResultHandler的HandlerResult包含处理程序的返回值和包含请求处理过程中添加的属性的模型。返回值按以下方式之一处理：

• String, CharSequence: A logical view name to be resolved to a View through the list of configured ViewResolver implementations.

• String, CharSequence: 一个要通过配置的一系列ViewResolver实现类解析为View的逻辑视图名称。

• void: Select a default view name based on the request path, minus the leading and trailing slash, and resolve it to a View. The same also happens when a view name was not provided (for example, model attribute was returned) or an async return value (for example, Mono completed empty).

• void：基于请求路径（减去前导和尾随斜杠）选择默认视图名称，并将其解析为View。当未提供视图名称（例如，返回模型属性）或异步返回值（例如，Mono完成为空）时，也会发生同样的情况。

• Rendering: API for view resolution scenarios. Explore the options in your IDE with code completion.

• 渲染：用于视图解析场景的 API。使用代码补全功能探索你的 IDE 中的选项。

• Model, Map: Extra model attributes to be added to the model for the request.

• Model, Map: 为请求添加到模型中的额外模型属性。

• Any other: Any other return value (except for simple types, as determined by BeanUtils#isSimpleProperty) is treated as a model attribute to be added to the model. The attribute name is derived from the class name by using conventions, unless a handler method @ModelAttribute annotation is present.

• 任何其他：任何其他返回值（除了由BeanUtils#isSimpleProperty确定的简单类型）都被视为要添加到模型中的模型属性。属性名称是根据约定从类名称派生的，除非存在@ModelAttribute注解的处理程序方法。

The model can contain asynchronous, reactive types (for example, from Reactor or RxJava). Prior to rendering, AbstractView resolves such model attributes into concrete values and updates the model. Single-value reactive types are resolved to a single value or no value (if empty), while multi-value reactive types (for example, Flux<T>) are collected and resolved to List<T>.

该模型可以包含异步、反应式类型（例如，来自 Reactor 或 RxJava）。在渲染之前，AbstractView将此类模型属性解析为具体值并更新模型。单值反应式类型被解析为单个值或无值（如果为空），而多值反应式类型（例如，Flux<T>）被收集并解析为List<T>。

To configure view resolution is as simple as adding a ViewResolutionResultHandler bean to your Spring configuration. WebFlux Config provides a dedicated configuration API for view resolution.

配置视图解析就像在 Spring 配置中添加一个ViewResolutionResultHandlerbean一样简单。WebFlux Config为视图解析提供了专用的配置 API。

See View Technologies for more on the view technologies integrated with Spring WebFlux.

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

Redirecting 【重定向】

The special redirect: prefix in a view name lets you perform a redirect. The UrlBasedViewResolver (and sub-classes) recognize this as an instruction that a redirect is needed. The rest of the view name is the redirect URL.

特殊redirect:视图名称中的前缀允许您执行重定向。UrlBasedViewResolver（及其子类）将此(前缀)识别为需要重定向的指令。视图名称的其余部分则是重定向URL。

The net effect is the same as if the controller had returned a RedirectView or Rendering.redirectTo("abc").build(), but now the controller itself can operate in terms of logical view names. A view name such as redirect:/some/resource is relative to the current application, while a view name such as redirect:https://example.com/arbitrary/path redirects to an absolute URL.

最终效果就像控制器返回了一个RedirectView或是 Rendering.redirectTo("abc").build()，但现在控制器本身可以根据逻辑视图名称进行操作。像 redirect:/some/resource样的视图名称是相对于当前应用程序，而像 redirect:https://example.com/arbitrary/path一样的视图名称则重定向到绝对 URL。

Content Negotiation 【内容协商】

ViewResolutionResultHandler supports content negotiation. It compares the request media types with the media types supported by each selected View. The first View that supports the requested media type(s) is used.

ViewResolutionResultHandler支持内容协商。它将请求的媒体类型与每个选定的View所支持的媒体类型进行比较。并使用首个支持请求的媒体类型的View 。

In order to support media types such as JSON and XML, Spring WebFlux provides HttpMessageWriterView, which is a special View that renders through an HttpMessageWriter. Typically, you would configure these as default views through the WebFlux Configuration. Default views are always selected and used if they match the requested media type.

为了支持 JSON 和 XML 等媒体类型，Spring WebFlux 提供了 HttpMessageWriterView(一个特殊的View，它通过HttpMessageWriter来渲染) 。通常，您可以通过WebFlux 配置将这些配置为默认视图。如果默认视图与请求的媒体类型匹配，则始终选择使用它们。

1.4. Annotated Controllers 【注解控制器】

Spring WebFlux provides an annotation-based programming model, where @Controller and @RestController components use annotations to express request mappings, request input, handle exceptions, and more. Annotated controllers have flexible method signatures and do not have to extend base classes nor implement specific interfaces.

Spring WebFlux 提供了一个基于注解的编程模型，其中@Controller和 @RestController组件使用注解来表达请求映射、请求输入、处理异常等。带注解的控制器具有灵活的方法签名，无需扩展基类或实现特定接口。

The following listing shows a basic example:

以下清单显示了一个基本示例：

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String handle() {
        return "Hello WebFlux";
    }
}

In the preceding example, the method returns a String to be written to the response body.

在前面的示例中，该方法返回的String会被写入响应体 。

1.4.1. @Controller

You can define controller beans by using a standard Spring bean definition. The @Controller stereotype allows for auto-detection and is aligned with Spring general support for detecting @Component classes in the classpath and auto-registering bean definitions for them. It also acts as a stereotype for the annotated class, indicating its role as a web component.

您可以使用标准的 Spring bean 定义方式来定义控制器 bean。@Controller原型允许自动检测，并与Spring通用支持一致，用于检测在 classpath 中被@Component注解的类并自动注册它们的bean定义。它还充当被注解类的原型，表明其作为 Web 组件的角色。

To enable auto-detection of such @Controller beans, you can add component scanning to your Java configuration, as the following example shows:

要启用诸如@Controllerbean 的自动检测，您可以将组件扫描添加到您的 Java 配置中，如以下示例所示：

@Configuration
@ComponentScan("org.example.web") //(1)
public class WebConfig {
	// ...
}

(1) Scan the org.example.web package.

(1) 扫描org.example.web包。

@RestController is a composed annotation that is itself meta-annotated with @Controller and @ResponseBody, indicating a controller whose every method inherits the type-level @ResponseBody annotation and, therefore, writes directly to the response body versus view resolution and rendering with an HTML template.

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

1.4.2. Request Mapping 【请求映射】

The @RequestMapping annotation is used to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media types. You can use it at the class level to express shared mappings or at the method level to narrow down to a specific endpoint mapping.

@RequestMapping注解用于将请求映射到控制器的方法。它有各种属性，可以和 URL、HTTP 方法、请求参数、请求头、媒体类型进行匹配。您可以在类级别使用它来表达共享映射，或者在方法级别使用它来缩小到特定端点映射。

There are also HTTP method specific shortcut variants of @RequestMapping:

还有关于@RequestMapping的特定于HTTP 方法(get、post...)的快捷变体：

• @GetMapping

• @PostMapping

• @PutMapping

• @DeleteMapping

• @PatchMapping

The preceding annotations are Custom Annotations that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus using @RequestMapping, which, by default, matches to all HTTP methods. At the same time, a @RequestMapping is still needed at the class level to express shared mappings.

前面的注解是提供的自定义注解，因为可以说，大多数控制器方法都应该映射到特定的 HTTP 方法，而不是使用 @RequestMapping，默认情况下，它与所有 HTTP 方法都匹配。同时，@RequestMapping仍然是需要的，在类级别上表达共享映射。

The following example uses type and method level mappings:

以下示例使用类型和方法级别映射：

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    public Person getPerson(@PathVariable Long id) {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public void add(@RequestBody Person person) {
        // ...
    }
}

URI Patterns 【URI 模版/式】

You can map requests by using glob patterns and wildcards:

您可以使用全局模式和通配符来映射请求：

Pattern	Description	Example
?	Matches one character 匹配一个字符	"/pages/t?st.html" matcAhes "/pages/test.html" and "/pages/t3st.html"
*	Matches zero or more characters within a path segment 匹配路径中的零个或多个字符	"/resources/*.png" matches "/resources/file.png" "/projects/\*/versions" matches "/projects/spring/versions" but does not match "/projects/spring/boot/versions"
**	Matches zero or more path segments until the end of the path 匹配零个或多个路径段直到路径结束	"/resources/**" matches "/resources/file.png" and "/resources/images/file.png" "/resources/**/file.png" is invalid as ** is only allowed at the end of the path.
{name}	Matches a path segment and captures it as a variable named "name" 匹配路径段并将其捕获为名为“name”的变量	"/projects/{project}/versions" matches "/projects/spring/versions" and captures project=spring
{name:[a-z]+}	Matches the regexp "[a-z]+" as a path variable named "name" 将正则表达式匹配"[a-z]+"为名为“name”的路径变量	"/projects/{project:[a-z]+}/versions" matches "/projects/spring/versions" but not "/projects/spring1/versions"
{*path}	Matches zero or more path segments until the end of the path and captures it as a variable named "path" 匹配零个或多个路径段直到路径的结尾并将其捕获为名为“path”的变量	"/resources/{*file}" matches "/resources/images/file.png" and captures file=/images/file.png

Captured URI variables can be accessed with @PathVariable, as the following example shows:

可以使用@PathVariable 来访问捕获的 URI 变量，如以下示例所示：

@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
    
}

You can declare URI variables at the class and method levels, as the following example shows:

您可以在类和方法级别声明 URI 变量，如以下示例所示：

@Controller
@RequestMapping("/owners/{ownerId}") //(1)
public class OwnerController {

    @GetMapping("/pets/{petId}") //(2)
    public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
        
    }
}

(1) Class-level URI mapping.
(2) Method-level URI mapping.

(1) 类级别的 URI 映射
(2) 方法级别的 URI 映射

URI variables are automatically converted to the appropriate type or a TypeMismatchException is raised. Simple types (int, long, Date, and so on) are supported by default and you can register support for any other data type. See Type Conversion and DataBinder.

URI 变量会自动转换为适当的类型或引发一个TypeMismatchException异常。默认情况下支持简单类型（int、long、Date等），另外您可以注册对任何其他数据类型的支持。请参阅类型转换和DataBinder.

URI variables can be named explicitly (for example, @PathVariable("customId")), but you can leave that detail out if the names are the same and you compile your code with debugging information or with the -parameters compiler flag on Java 8.

可以显式命名 URI 变量（例如，@PathVariable("customId")），但如果名称相同并且您使用调试信息或Java 8 上的-parameters编译器标志来编译代码，则可以省略该细节。

The syntax {*varName} declares a URI variable that matches zero or more remaining path segments. For example /resources/{*path} matches all files under /resources/, and the "path" variable captures the complete path under /resources.

{*varName}语法声明了一个匹配零个或多个剩余路径段的 URI 变量。例如/resources/{*path}匹配/resources/下的所有文件，"path"变量捕获/resources 下的完整路径。

The syntax {varName:regex} declares a URI variable with a regular expression that has the syntax: {varName:regex}. For example, given a URL of /spring-web-3.0.5.jar, the following method extracts the name, version, and file extension:

{varName:regex}语法声明了一个带有正则表达式的 URI 变量，其语法为：{varName:regex}。例如，给定 URL /spring-web-3.0.5.jar，以下方法提取名称、版本和文件扩展名：

@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
public void handle(@PathVariable String version, @PathVariable String ext) {
    
}

URI path patterns can also have embedded ${…} placeholders that are resolved on startup through PropertyPlaceHolderConfigurer against local, system, environment, and other property sources. You ca use this to, for example, parameterize a base URL based on some external configuration.

URI 路径模式还可以具有嵌入的${…}占位符，这些占位符在启动时通过PropertyPlaceHolderConfigurer针对本地、系统、环境和其他属性源进行解析。例如，您可以使用它根据某些外部配置来参数化一个基础URL。

Spring WebFlux uses PathPattern and the PathPatternParser for URI path matching support. Both classes are located in spring-web and are expressly designed for use with HTTP URL paths in web applications where a large number of URI path patterns are matched at runtime.

Spring WebFlux 使用PathPattern和PathPatternParser来进行 URI 路径匹配支持。这两个类都位于spring-web中并专门设计来和Web 应用程序(在运行时会匹配大量 URI 路径模式)中的 HTTP URL 路径一起使用。

Spring WebFlux does not support suffix pattern matching — unlike Spring MVC, where a mapping such as /person also matches to /person.*. For URL-based content negotiation, if needed, we recommend using a query parameter, which is simpler, more explicit, and less vulnerable to URL path based exploits.

与 Spring MVC 不同，Spring WebFlux 不支持后缀模式匹配，其中诸如/person也匹配到/person.*这样的映射. 对于基于 URL 的内容协商，如果需要，我们建议使用查询参数，更简单、更明确且不易受到基于 URL 路径的攻击。

Pattern Comparison 【模式比较】

When multiple patterns match a URL, they must be compared to find the best match. This is done with PathPattern.SPECIFICITY_COMPARATOR, which looks for patterns that are more specific.

当多个模式都匹配一​​个 URL 时，必须比较它们以找到最佳匹配。这要用到PathPattern.SPECIFICITY_COMPARATOR，它用于寻找更具体的模式。

For every pattern, a score is computed, based on the number of URI variables and wildcards, where a URI variable scores lower than a wildcard. A pattern with a lower total score wins. If two patterns have the same score, the longer is chosen.

对于每个模式，都会根据 URI 变量和通配符的数量计算一个分数，其中 URI 变量的分数低于通配符。总分较低的模式获胜。如果两个模式具有相同的分数，则选择较长的。

Catch-all patterns (for example, **, {*varName}) are excluded from the scoring and are always sorted last instead. If two patterns are both catch-all, the longer is chosen.

Catch-all 模式（例如，**, {*varName}）被排除在评分之外，并且总是排在最后。如果两种模式都包罗万象，则选择较长的。

Consumable Media Types 【可使用的媒体类型】

You can narrow the request mapping based on the Content-Type of the request, as the following example shows:

您可以根据请求的Content-Type来缩小请求映射范围，如下例所示：

@PostMapping(path = "/pets", consumes = "application/json")
public void addPet(@RequestBody Pet pet) {
    // ...
}

The consumes attribute also supports negation expressions — for example, !text/plain means any content type other than text/plain.

consumes属性还支持否定表达式 - 例如，!text/plain表示除text/plain.

You can declare a shared consumes attribute at the class level. Unlike most other request mapping attributes, however, when used at the class level, a method-level consumes attribute overrides rather than extends the class-level declaration.

您可以在类级别上声明共享的consumes属性。然而，与大多数其他请求映射属性不同，当在类级别使用时，方法级别的consumes属性会覆盖而不是扩展类级别的声明。

MediaType provides constants for commonly used media types — for example, APPLICATION_JSON_VALUE and APPLICATION_XML_VALUE.

MediaType为常用的媒体类型提供常量——例如， APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE。

Producible Media Types 【可产生的媒体类型】

You can narrow the request mapping based on the Accept request header and the list of content types that a controller method produces, as the following example shows:

您可以根据Accept请求头和控制器方法produces变量的内容/媒体类型列表来缩小请求映射范围，如下例所示：

@GetMapping(path = "/pets/{petId}", produces = "application/json")
@ResponseBody
public Pet getPet(@PathVariable String petId) {
    // ...
}

The media type can specify a character set. Negated expressions are supported — for example, !text/plain means any content type other than text/plain.

媒体类型可以指定一个字符集。支持否定表达式 - 例如， !text/plain表示除text/plain.

You can declare a shared produces attribute at the class level. Unlike most other request mapping attributes, however, when used at the class level, a method-level produces attribute overrides rather than extend the class level declaration.

您可以在类级别上声明共享produces属性。然而，与大多数其他请求映射属性不同，当在类级别使用时，方法级别的produces属性会覆盖而不是扩展类级别的声明。

MediaType provides constants for commonly used media types — e.g. APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE.

MediaType为常用的媒体类型提供常量——例如 APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE.

Parameters and Headers 【参数和头信息】

You can narrow request mappings based on query parameter conditions. You can test for the presence of a query parameter (myParam), for its absence (!myParam), or for a specific value (myParam=myValue). The following examples tests for a parameter with a value:

您可以根据查询参数条件缩小请求映射范围。您可以测试是否存在查询参数 ( myParam)、是否不存在 ( !myParam) 或是否是特定值 ( myParam=myValue)。以下示例测试是否为具体值的参数：

@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") //(1)
public void findPet(@PathVariable String petId) {
    // ...
}

(1) Check that myParam equals myValue.
(1) 检查是否myParam等于myValue.

You can also use the same with request header conditions, as the follwing example shows:

您还可以对请求头条件使用相同的内容，如以下示例所示：

@GetMapping(path = "/pets", headers = "myHeader=myValue") (1)
public void findPet(@PathVariable String petId) {
    // ...
}

(1) Check that myHeader equals myValue.
(1) 检查是否myHeader等于myValue.

HTTP HEAD, OPTIONS 【HTTP 头，选项】

@GetMapping and @RequestMapping(method=HttpMethod.GET) support HTTP HEAD transparently for request mapping purposes. Controller methods need not change. A response wrapper, applied in the HttpHandler server adapter, ensures a Content-Length header is set to the number of bytes written without actually writing to the response.

@GetMapping和@RequestMapping(method=HttpMethod.GET)透明地支持 HTTP HEAD 用于请求映射目的。控制器方法不需要改变。在服务器适配器HttpHandler中应用的响应包装器可以确保将Content-Length 头设置为写入的字节数，而无需实际写入响应。

By default, HTTP OPTIONS is handled by setting the Allow response header to the list of HTTP methods listed in all @RequestMapping methods with matching URL patterns.

默认情况下，HTTP OPTIONS 的处理方式是将Allow响应头设置为所有URL模式能匹配得上的@RequestMapping方法中列出的 HTTP 方法列表。

For a @RequestMapping without HTTP method declarations, the Allow header is set to GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS. Controller methods should always declare the supported HTTP methods (for example, by using the HTTP method specific variants — @GetMapping, @PostMapping, and others).

对于没有 HTTP 方法声明的@RequestMapping ，Allow头被设置为 GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。控制器方法应始终声明支持的 HTTP 方法（例如，通过使用特定于 HTTP 方法的变体 —  @GetMapping、@PostMapping等）。

You can explicitly map a @RequestMapping method to HTTP HEAD and HTTP OPTIONS, but that is not necessary in the common case.

您可以将@RequestMapping方法显式映射到 HTTP HEAD 和 HTTP OPTIONS，但这在常见情况下不是必需的。

Custom Annotations 【自定义注解】

Spring WebFlux supports the use of composed annotations for request mapping. Those are annotations that are themselves meta-annotated with @RequestMapping and composed to redeclare a subset (or all) of the @RequestMapping attributes with a narrower, more specific purpose.

Spring WebFlux 支持使用组合注解 进行请求映射。这些注解本身是被@RequestMapping元注解的， 并被组合起来以更窄、更具体的目的重新声明为@RequestMapping 属性的子集（或全部）。

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, and @PatchMapping are examples of composed annotations. They are provided, because, arguably, most controller methods should be mapped to a specific HTTP method versus using @RequestMapping, which, by default, matches to all HTTP methods. If you need an example of composed annotations, look at how those are declared.

@GetMapping、@PostMapping、@PutMapping、@DeleteMapping和@PatchMapping是组合注解的示例。之所以提供它们，是因为可以说，大多数控制器方法应该映射到特定的 HTTP 方法，而不是直接使用@RequestMapping，默认情况下，它与所有 HTTP 方法匹配。如果您需要组合注解的示例，请查看它们是如何声明的。

Spring WebFlux also supports custom request mapping attributes with custom request matching logic. This is a more advanced option that requires sub-classing RequestMappingHandlerMapping and overriding the getCustomMethodCondition method, where you can check the custom attribute and return your own RequestCondition.

Spring WebFlux 还支持具有自定义请求匹配逻辑的自定义请求映射属性。这是一个更高级的选项，需要继承 RequestMappingHandlerMapping并重写getCustomMethodCondition方法，您可以在其中检查自定义属性并返回您自己的RequestCondition.

Explicit Registrations 【显式注册】

You can programmatically register Handler methods, which can be used for dynamic registrations or for advanced cases, such as different instances of the same handler under different URLs. The following example shows how to do so:

您可以通过编程方式注册Handler方法，可以用于动态注册，也可以用于更高级情况，例如同一个handler在不同URL下的不同实例。以下示例显示了如何执行此操作：

@Configuration
public class MyConfig {
    @Autowired
    public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) //(1)
            throws NoSuchMethodException {

        RequestMappingInfo info = RequestMappingInfo
                .paths("/user/{id}").methods(RequestMethod.GET).build(); //(2)

        Method method = UserHandler.class.getMethod("getUser", Long.class); //(3)

        mapping.registerMapping(info, handler, method); //(4)
    }
}

(1) Inject target handlers and the handler mapping for controllers.
(2) Prepare the request mapping metadata.
(3) Get the handler method.
(4) Add the registration.

(1) 注入目标处理程序和控制器的处理程序映射。
(2) 准备请求映射元数据。
(3) 获取处理程序方法。
(4) 添加注册。

1.4.3. Handler Methods 【Handler 方法】

@RequestMapping handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values.

@RequestMapping 注解的处理方法具有灵活的签名，可以从一系列受支持的控制器方法参数和返回值中进行选择。

Method Arguments 【方法参数】

The following table shows the supported controller method arguments.

下表显示了支持的控制器方法参数。

Reactive types (Reactor, RxJava, or other) are supported on arguments that require blocking I/O (for example, reading the request body) to be resolved. This is marked in the Description column. Reactive types are not expected on arguments that do not require blocking.

方法参数要支持反应类型（Reactor、RxJava或其他）需要解决阻塞 I/O（例如，读取请求体）。这在下表''描述''一列中被提及。不需要阻塞的参数不需要反应类型。

JDK 1.8’s java.util.Optional is supported as a method argument in combination with annotations that have a required attribute (for example, @RequestParam, @RequestHeader, and others) and is equivalent to required=false.

JDK 1.8的java.util.Optional被作为方法参数与具有required属性的注解（例如，@RequestParam，@RequestHeader，等）一起受到支持，就相当于required=false。

Controller method argument	Description	描述
ServerWebExchange	Access to the full ServerWebExchange — container for the HTTP request and response, request and session attributes, checkNotModified methods, and others.	访问完整的ServerWebExchange — 用于 HTTP 请求和响应、请求和会话属性、checkNotModified方法等的容器。
ServerHttpRequest, ServerHttpResponse	Access to the HTTP request or response.	访问 HTTP 请求或响应。
WebSession	Access to the session. This does not force the start of a new session unless attributes are added. Supports reactive types.	访问会话。除非添加属性，否则这不会强制启动新会话。支持反应式。
java.security.Principal	The currently authenticated user — possibly a specific Principal implementation class if known. Supports reactive types.	当前经过身份验证的用户 — 如果可知可能是一个特殊的Principal实现类。支持反应式。
org.springframework.http.HttpMethod	The HTTP method of the request.	请求的 HTTP 方法。
java.util.Locale	The current request locale, determined by the most specific LocaleResolver available — in effect, the configured LocaleResolver/LocaleContextResolver.	当前请求地区，由最具体的LocaleResolver可用区域确定——实际上是配置的LocaleResolver/ LocaleContextResolver。
java.util.TimeZone + java.time.ZoneId	The time zone associated with the current request, as determined by a LocaleContextResolver.	与当前请求关联的时区，由 LocaleContextResolver确定。
@PathVariable	For access to URI template variables. See URI Patterns.	用于访问 URI 模板变量。请参阅URI 模式。
@MatrixVariable	For access to name-value pairs in URI path segments. See Matrix Variables.	用于访问 URI 路径段中的名称 - 值对。请参阅矩阵变量。
@RequestParam	For access to Servlet request parameters. Parameter values are converted to the declared method argument type. See @RequestParam. Note that use of @RequestParam is optional — for example, to set its attributes. See “Any other argument” later in this table.	用于访问 Servlet 请求参数。参数值被转换为声明的方法参数类型。参见@RequestParam。 请注意，使用@RequestParam是可选的——例如，设置其属性。请参阅此表后面的“任何其他参数”。
@RequestHeader	For access to request headers. Header values are converted to the declared method argument type. See @RequestHeader.	用于访问请求头。请求头的值转换为所声明的方法参数的类型。见@RequestHeader。
@CookieValue	For access to cookies. Cookie values are converted to the declared method argument type. See @CookieValue.	用于访问 cookie。Cookie 值被转换为所声明的方法参数的类型。见@CookieValue。
@RequestBody	For access to the HTTP request body. Body content is converted to the declared method argument type by using HttpMessageReader instances. Supports reactive types. See @RequestBody.	用于访问 HTTP 请求正文。正文内容通过使用HttpMessageReader实例转换为所声明的方法参数类型。支持反应式。见@RequestBody。
HttpEntity<B>	For access to request headers and body. The body is converted with HttpMessageReader instances. Supports reactive types. See HttpEntity.	用于访问请求头和正文。正文是用HttpMessageReader实例转换的。支持反应式。见HttpEntity。
@RequestPart	For access to a part in a multipart/form-data request. Supports reactive types. See Multipart Content and Multipart Data.	用于访问multipart/form-data表单请求中的一部分。支持反应式。请参阅多部分内容和多部分数据。
java.util.Map, org.springframework.ui.Model, and org.springframework.ui.ModelMap.	For access to the model that is used in HTML controllers and is exposed to templates as part of view rendering.	用于访问在 HTML 控制器中使用的模型，并作为视图渲染的部分的模板公开/暴露。
@ModelAttribute	For access to an existing attribute in the model (instantiated if not present) with data binding and validation applied. See @ModelAttribute as well as Model and DataBinder. Note that use of @ModelAttribute is optional — for example, to set its attributes. See “Any other argument” later in this table.	用于访问模型中的现有属性（如果不存在则实例化）进行数据绑定和验证。见@ModelAttribute以及Model和DataBinder。 请注意，使用@ModelAttribute是可选的——例如，设置其属性。请参阅此表后面的“任何其他参数”。
Errors, BindingResult	For access to errors from validation and data binding for a command object, i.e. a @ModelAttribute argument. An Errors, or BindingResult argument must be declared immediately after the validated method argument.	用于访问验证的错误和命令对象的数据绑定结果，例如@ModelAttribute参数。Errors或BindingResult参数必须在有效的方法参数后立即声明。
SessionStatus + class-level @SessionAttributes	For marking form processing complete, which triggers cleanup of session attributes declared through a class-level @SessionAttributes annotation. See @SessionAttributes for more details.	用于标记表单处理完成，这会触发会话属性(通过类级@SessionAttributes注解声明的清理）。请参阅@SessionAttributes获取更多详细信息，。
UriComponentsBuilder	For preparing a URL relative to the current request’s host, port, scheme, and context path. See URI Links.	用于准备相对于当前请求的主机、端口、方案和上下文路径的 URL。请参阅URI 链接。
@SessionAttribute	For access to any session attribute — in contrast to model attributes stored in the session as a result of a class-level @SessionAttributes declaration. See @SessionAttribute for more details.	用于访问任何会话属性——与作为(类级@SessionAttributes注解所声明)结果存储在会话中的模型属性相反。更多详细信息请参阅@SessionAttribute 。
@RequestAttribute	For access to request attributes. See @RequestAttribute for more details.	用于访问请求属性。更多详细信息请参阅@RequestAttribute。
Any other argument	If a method argument is not matched to any of the above, it is, by default, resolved as a @RequestParam if it is a simple type, as determined by BeanUtils#isSimpleProperty, or as a @ModelAttribute, otherwise.	如果方法参数与上述任何一个都不匹配，则默认情况下，如果它是简单类型(由BeanUtils#isSimpleProperty确定 @ModelAttribute)，则作为@RequestParam解析，否则作为 @ModelAttribute解析 。

Return Values 【返回值】

The following table shows the supported controller method return values. Note that reactive types from libraries such as Reactor, RxJava, or other are generally supported for all return values.

下表显示了支持的控制器方法返回值。请注意，所有返回值通常都支持来自 Reactor、RxJava或其他库的反应式类型。

Controller method return value	Description	描述
@ResponseBody	The return value is encoded through HttpMessageWriter instances and written to the response. See @ResponseBody.	返回值通过HttpMessageWriter实例编码并写入响应。见@ResponseBody。
HttpEntity<B>, ResponseEntity<B>	The return value specifies the full response, including HTTP headers, and the body is encoded through HttpMessageWriter instances and written to the response. See ResponseEntity.	返回值指定完整的响应，包括 HTTP 头和正文(通过HttpMessageWriter实例编码并写入响应)。见ResponseEntity。
HttpHeaders	For returning a response with headers and no body.	用于返回带有头信息但没有正文的响应。
String	A view name to be resolved with ViewResolver instances and used together with the implicit model — determined through command objects and @ModelAttribute methods. The handler method can also programmatically enrich the model by declaring a Model argument (described earlier).	一个视图名称，被ViewResolver实例解析并与隐式模型(通过命令对象和@ModelAttribute方法确定)一起使用。处理程序方法还可以通过声明一个Model参数（前面描述过）以编程方式丰富模型。
View	A View instance to use for rendering together with the implicit model — determined through command objects and @ModelAttribute methods. The handler method can also programmatically enrich the model by declaring a Model argument (described earlier).	一个View实例 —— 用于与所述隐式模型(由命令对象和@ModelAttribute方法确定)一起渲染。处理程序方法还可以通过声明一个Model参数（前面描述过）以编程方式丰富模型。
java.util.Map, org.springframework.ui.Model	Attributes to be added to the implicit model, with the view name implicitly determined based on the request path.	要添加到隐式模型的属性，视图名称根据请求路径隐式确定。
@ModelAttribute	An attribute to be added to the model, with the view name implicitly determined based on the request path. Note that @ModelAttribute is optional. See “Any other return value” later in this table.	要添加到模型的属性，视图名称根据请求路径隐式确定。 注意，@ModelAttribute是可选的。请参阅此表后面的“任何其他返回值”。
Rendering	An API for model and view rendering scenarios.	用于模型和视图渲染场景的 API。
void	A method with a void, possibly asynchronous (for example, Mono<Void>), return type (or a null return value) is considered to have fully handled the response if it also has a ServerHttpResponse, a ServerWebExchange argument, or an @ResponseStatus annotation. The same is also true if the controller has made a positive ETag or lastModified timestamp check. // TODO: See Controllers for details. If none of the above is true, a void return type can also indicate “no response body” for REST controllers or default view name selection for HTML controllers.	如果方法是void，那它可能是异步的（例如，Mono<Void>），返回类型（或null返回值），则被认为已经完全处理了响应(如果它还有一个ServerHttpResponse、一个ServerWebExchange参数或@ResponseStatus注解)。如果控制器进行了正面的 ETag 或lastModified时间戳检查，情况也是如此。// TODO：有关详细信息，请参阅控制器。 如果以上都不为真，则void返回类型也可表明 REST 控制器的“无响应正文”或 HTML 控制器选择默认视图名称。
Flux<ServerSentEvent>, Observable<ServerSentEvent>, or other reactive type	Emit server-sent events. The ServerSentEvent wrapper can be omitted when only data needs to be written (however, text/event-stream must be requested or declared in the mapping through the produces attribute).	发出服务器发送事件。当只需要写入数据时，可以省略ServerSentEvent包装器（但是，text/event-stream是必须的，或通过produces属性在映射中声明）。
Any other return value	If a return value is not matched to any of the above, it is, by default, treated as a view name, if it is String or void (default view name selection applies), or as a model attribute to be added to the model, unless it is a simple type, as determined by BeanUtils#isSimpleProperty, in which case it remains unresolved.	如果返回值与上述任何一项都不匹配，则默认情况下将其视为视图名称 —— 如果返回值是String或void（适用默认视图名称选择），或视为要添加到模型的模型属性，若它是一个由BeanUtils#isSimpleProperty确定的简单类型，则在这种情况下它仍未解决。

Type Conversion 【类型转换】

Some annotated controller method arguments that represent String-based request input (for example, @RequestParam, @RequestHeader, @PathVariable, @MatrixVariable, and @CookieValue) can require type conversion if the argument is declared as something other than String.

某些被注解的控制器方法参数 —— 其本身代表的是字符串类的请求输入（例如， @RequestParam, @RequestHeader, @PathVariable, @MatrixVariable, 和@CookieValue）可能需要进行类型转换 —— 如果参数被声明为非String类型。

For such cases, type conversion is automatically applied based on the configured converters. By default, simple types (such as int, long, Date, and others) are supported. Type conversion can be customized through a WebDataBinder (see DataBinder) or by registering Formatters with the FormattingConversionService (see Spring Field Formatting).

对于这种情况，会根据配置的转换器自动进行类型转换。默认情况下，支持简单类型（如int，long，Date，等）。类型转换可通过WebDataBinder（见DataBinder）或通过FormattingConversionService注册 Formatters来实现自定义（参见Spring Field Formatting）。

A practical issue in type conversion is the treatment of an empty String source value. Such a value is treated as missing if it becomes null as a result of type conversion. This can be the case for Long, UUID, and other target types. If you want to allow null to be injected, either use the required flag on the argument annotation, or declare the argument as @Nullable.

类型转换中的一个实际问题是空字符串源值的处理。如果接受null作为类型转换的结果，则将此类值视为缺失值。这样可以处理转换目标类型是Long，UUID或其他类型的情况。如果要允许null 注入，请在参数上使用required注解，或将参数声明为@Nullable.

Matrix Variables 【矩阵变量】

RFC 3986 discusses name-value pairs in path segments. In Spring WebFlux, we refer to those as “matrix variables” based on an “old post” by Tim Berners-Lee, but they can be also be referred to as URI path parameters.

RFC 3986讨论了路径段中的 名称-值 对。在 Spring WebFlux 中，我们将它们称为基于Tim Berners-Lee的“old post”的“矩阵变量” ，但它们也可以称为 URI 路径参数。

Matrix variables can appear in any path segment, with each variable separated by a semicolon and multiple values separated by commas — for example, "/cars;color=red,green;year=2012". Multiple values can also be specified through repeated variable names — for example, "color=red;color=green;color=blue".

矩阵变量可以出现在任何路径段中，每个变量用分号分隔，多个值用逗号分隔 —— 例如，"/cars;color=red,green;year=2012". 也可以通过重复的变量名来指定多个值——例如， "color=red;color=green;color=blue".

Unlike Spring MVC, in WebFlux, the presence or absence of matrix variables in a URL does not affect request mappings. In other words, you are not required to use a URI variable to mask variable content. That said, if you want to access matrix variables from a controller method, you need to add a URI variable to the path segment where matrix variables are expected. The following example shows how to do so:

与 Spring MVC 不同，在 WebFlux 中，URL 中矩阵变量的存在与否不会影响请求映射。换句话说，您不需要使用 URI 变量来屏蔽变量内容。也就是说，如果要从控制器方法访问矩阵变量，则需要将 URI 变量添加到矩阵变量应在的路径段中。以下示例显示了如何执行此操作：

// GET /pets/42;q=11;r=22
@GetMapping("/pets/{petId}")
public void findPet(@PathVariable String petId, @MatrixVariable int q) {
    // petId == 42
    // q == 11
}

Given that all path segments can contain matrix variables, you may sometimes need to disambiguate which path variable the matrix variable is expected to be in, as the following example shows:

鉴于所有路径段都可以包含矩阵变量，您有时可能需要消除矩阵变量应位于哪个路径变量中的歧义，如以下示例所示：

// GET /owners/42;q=11/pets/21;q=22
@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable() int q1,
        @MatrixVariable() int q2) {
    // q1 == 11
    // q2 == 22
}

You can define a matrix variable may be defined as optional and specify a default value as the following example shows:

您可以定义一个可选并指定默认值矩阵变量，如下例所示：

// GET /pets/42
@GetMapping("/pets/{petId}")
public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) {
	// q == 1
}

To get all matrix variables, use a MultiValueMap, as the following example shows:

使用 MultiValueMap可以获取所有矩阵变量，如以下示例所示：

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23
@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable MultiValueMap<String, String> matrixVars,
        @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {
    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

@RequestParam

You can use the @RequestParam annotation to bind query parameters to a method argument in a controller. The following code snippet shows the usage:

您可以使用@RequestParam注解将查询参数绑定到控制器的方法参数上。以下代码片段显示了用法：

@Controller
@RequestMapping("/pets")
public class EditPetForm {
    // ...
    @GetMapping
    public String setupForm(@RequestParam("petId") int petId, Model model) { //(1)
        Pet pet = this.clinic.loadPet(petId);
        model.addAttribute("pet", pet);
        return "petForm";
    }
    // ...
}

(1) Using @RequestParam.

The Servlet API “request parameter” concept conflates query parameters, form data, and multiparts into one. However, in WebFlux, each is accessed individually through ServerWebExchange. While @RequestParam binds to query parameters only, you can use data binding to apply query parameters, form data, and multiparts to a command object.

Servlet API“请求参数”概念将查询参数、表单数据和多部分合而为一。但是，在 WebFlux 中，每个都可以通过 ServerWebExchange单独获取。 虽然@RequestParam仅绑定到查询参数，但您可以使用数据绑定将查询参数、表单数据和多部分应用于 command object。

Method parameters that use the @RequestParam annotation are required by default, but you can specify that a method parameter is optional by setting the required flag of a @RequestParam to false or by declaring the argument with a java.util.Optional wrapper.

默认情况下，使用@RequestParam注解的方法参数是必需的，但你可以通过给@RequestParam设置 require=false或使用java.util.Optional 包装器来声明参数的方式指定方法参数是可选的。

Type conversion is applied automatically if the target method parameter type is not String. See Type Conversion.

如果目标方法参数类型不是String，则自动应用类型转换(因为进来的请求的请求path、内容等都是编码成字符串传来的)。请参阅类型转换。

When a @RequestParam annotation is declared on a Map<String, String> or MultiValueMap<String, String> argument, the map is populated with all query parameters.

如果 @RequestParam 注解被声明在了Map<String, String>或MultiValueMap<String, String>类型的参数上，则所有的查询参数都将被填充进对应的map。

Note that use of @RequestParam is optional — for example, to set its attributes. By default, any argument that is a simple value type (as determined by BeanUtils#isSimpleProperty) and is not resolved by any other argument resolver is treated as if it were annotated with @RequestParam.

请注意，使用@RequestParam是可选的 —— 例如，设置其属性。默认情况下，任何属于简单值类型（由BeanUtils#isSimpleProperty确定 ）且未被任何其他参数解析器解析的参数都被视为使用@RequestParam.

You can use the @RequestHeader annotation to bind a request header to a method argument in a controller.

您可以使用@RequestHeader注解将请求头绑定到控制器的方法参数上。

The following example shows a request with headers:

以下示例显示了一个带有标头的请求：

Host                    localhost:8080
Accept                  text/html,application/xhtml+xml,application/xml;q=0.9
Accept-Language         fr,en-gb;q=0.7,en;q=0.3
Accept-Encoding         gzip,deflate
Accept-Charset          ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive              300

The following example gets the value of the Accept-Encoding and Keep-Alive headers:

以下示例获取Accept-Encoding和Keep-Alive请求头的值：

@GetMapping("/demo")
public void handle(
        @RequestHeader("Accept-Encoding") String encoding, //(1)
        @RequestHeader("Keep-Alive") long keepAlive) { //(2)
    //...
}

(1) Get the value of the Accept-Encoging header.
(2) Get the value of the Keep-Alive header.

(1) 获取Accept-Encoging标题的值。
(2) 获取Keep-Alive标题的值。

Type conversion is applied automatically if the target method parameter type is not String. See Type Conversion.

如果目标方法参数类型不是String，则自动应用类型转换。请参阅类型转换。

When a @RequestHeader annotation is used on a Map<String, String>, MultiValueMap<String, String>, or HttpHeaders argument, the map is populated with all header values.

如果 @RequestHeader 注解被声明在了Map<String, String>或MultiValueMap<String, String>类型的参数上，则所有的查询参数都将被填充进对应的map。

Built-in support is available for converting a comma-separated string into an array or collection of strings or other types known to the type conversion system. For example, a method parameter annotated with @RequestHeader("Accept") may be of type String but also of String[] or List<String>.

内置地支持将逗号分隔的字符串转换为数组或字符串集合或类型转换系统已知的其他类型。例如，@RequestHeader("Accept")注解的方法参数， 可以声明为String类型，也可以是String[]或List<String>。

@CookieValue

You can use the @CookieValue annotation to bind the value of an HTTP cookie to a method argument in a controller.

您可以使用@CookieValue注解将 HTTP cookie 的值绑定到控制器的方法参数上。

The following example shows a request with a cookie:

以下示例显示了一个带有 cookie 的请求：

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

The following code sample demonstrates how to get the cookie value:

以下代码示例演示了如何获取 cookie 值：

@GetMapping("/demo")
public void handle(@CookieValue("JSESSIONID") String cookie) { (1)
    //...
}

Type conversion is applied automatically if the target method parameter type is not String. See Type Conversion.

如果目标方法参数类型不是String，则自动应用类型转换 。请参阅类型转换。

@ModelAttribute

You can use the @ModelAttribute annotation on a method argument to access an attribute from the model or have it instantiated if not present. The model attribute is also overlaid with the values of query parameters and form fields whose names match to field names. This is referred to as data binding, and it saves you from having to deal with parsing and converting individual query parameters and form fields. The following example binds an instance of Pet:

您可以在方法参数上使用@ModelAttribute注解来访问模型中的属性，或者在不存在的情况下对其进行实例化。模型属性还会被与其字段名称匹配的查询参数的值或表单字段的值覆盖。这被称为数据绑定，它使您不必去处理单个查询参数和表单字段的解析和转换。以下示例绑定一个Pet实例：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } //(1)

(1) Bind an instance of Pet

(1) 绑定一个Pet实例。

The Pet instance in the preceding example is resolved as follows:

上述Pet实例的解析如下：

• From the model if already added through Model.

• 从model得到，如果已经通过Model添加.

• From the HTTP session through @SessionAttributes.

• 从@SessionAttributes 注解的HTTP session 得到，.

• From the invocation of a default constructor.

• 从调用默认构造函数得到

• From the invocation of a “primary constructor” with arguments that match query parameters or form fields. Argument names are determined through JavaBeans @ConstructorProperties or through runtime-retained parameter names in the bytecode.

• 从调用与查询参数或表单字段参数相匹配的“主构造函数”得到。参数名称是由 JavaBeans @ConstructorProperties或字节码中运行时保留的参数名称确定的。

After the model attribute instance is obtained, data binding is applied. The WebExchangeDataBinder class matches names of query parameters and form fields to field names on the target Object. Matching fields are populated after type conversion is applied where necessary. For more on data binding (and validation), see Validation. For more on customizing data binding, see DataBinder.

获取模型属性实例后，应用数据绑定。WebExchangeDataBinder类将查询参数和表单字段的名称与目标Object的属性字段名称进行匹配。之后填充匹配的字段(必要时应用类型转换)。有关数据绑定（和验证）的更多信息，请参阅 Validation。有关自定义数据绑定的更多信息，请参阅 DataBinder。

Data binding can result in errors. By default, a WebExchangeBindException is raised, but, to check for such errors in the controller method, you can add a BindingResult argument immediately next to the @ModelAttribute, as the following example shows:

数据绑定可能会导致错误。默认情况下， 引发一个WebExchangeBindException，但是，要检查控制器方法中的此类错误，您可以在@ModelAttribute后立即添加一个BindingResult参数，如下例所示：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { //(1)
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}

(1) Adding a BindingResult.

You can automatically apply validation after data binding by adding the javax.validation.Valid annotation or Spring’s @Validated annotation (see also Bean Validation and Spring validation). The following example uses the @Valid annotation:

您可以通过在数据绑定后添加javax.validation.Valid注解或 Spring 的@Validated注解（另请参阅 Bean 验证和 Spring 验证）自动应用验证 。以下示例使用了@Valid注解：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { //(1)
    if (result.hasErrors()) {
        return "petForm";
    }
}

(1) Using @Valid on a model attribute argument.

(1) 在一个模型属性参数上使用@Valid。

Spring WebFlux, unlike Spring MVC, supports reactive types in the model — for example, Mono<Account> or io.reactivex.Single<Account>. You can declare a @ModelAttribute argument with or without a reactive type wrapper, and it will be resolved accordingly, to the actual value if necessary. However, note that, to use a BindingResult argument, you must declare the @ModelAttribute argument before it without a reactive type wrapper, as shown earlier. Alternatively, you can handle any errors through the reactive type, as the following example shows:

Spring WebFlux 与 Spring MVC 不同，它在模型中支持响应式类型——例如， Mono<Account>或io.reactivex.Single<Account>. 您可以使用或不使用反应式类型包装器来声明一个@ModelAttribute参数，根据情况处理，如有必要，依据实际值。但是，请注意，要使用BindingResult 参数，您声明@ModelAttribute参数必须在其没有反应类型包装器之前，就如前面所述一样。或者，您可以通过反应式类型处理任何错误，如以下示例所示：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) {
    return petMono
        .flatMap(pet -> {
            // ...
        })
        .onErrorResume(ex -> {
            // ...
        });
}

Note that use of @ModelAttribute is optional — for example, to set its attributes. By default, any argument that is not a simple value type( as determined by BeanUtils#isSimpleProperty) and is not resolved by any other argument resolver is treated as if it were annotated with @ModelAttribute.

请注意，使用@ModelAttribute是可选的——例如，设置其属性。默认情况下，任何不是简单值类型（由BeanUtils#isSimpleProperty确定 ）并且未被任何其他参数解析器解析的参数都被视为使用@ModelAttribute注解。

@SessionAttributes

@SessionAttributes is used to store model attributes in the WebSession between requests. It is a type-level annotation that declares session attributes used by a specific controller. This typically lists the names of model attributes or types of model attributes that should be transparently stored in the session for subsequent requests to access.

@SessionAttributes用于存储请求之间的WebSession的模型属性。它是一个类级别的注解，用于声明特定控制器使用的会话属性。这通常会列出模型属性的名称或模型属性的类型 —— 应该透明地存储在会话中以供后续请求访问。

Consider the following example:

考虑以下示例：

@Controller
@SessionAttributes("pet") //(1)
public class EditPetForm {
    // ...
}

(1) Using the @SessionAttributes annotation.

(1) 使用@SessionAttributes注解。

On the first request, when a model attribute with the name, pet, is added to the model, it is automatically promoted to and saved in the WebSession. It remains there until another controller method uses a SessionStatus method argument to clear the storage, as the following example shows:

在第一个请求中，当一个名为pet的模型属性被添加到模型中时，它会自动提升并保存在WebSession中。它一致保存在那里，直到另一个使用SessionStatus方法参数的控制器方法来清除存储，如以下示例所示：

@Controller
@SessionAttributes("pet") //(1)
public class EditPetForm {
    // ...
    @PostMapping("/pets/{id}")
    public String handle(Pet pet, BindingResult errors, SessionStatus status) { //(2)
        if (errors.hasErrors()) {
            // ...
        }
            status.setComplete();
            // ...
        }
    }
}

(1) Using the @SessionAttributes annotation.
(2) Using a SessionStatus variable.

@SessionAttribute

If you need access to pre-existing session attributes that are managed globally (that is, outside the controller — for example, by a filter) and may or may not be present, you can use the @SessionAttribute annotation on a method parameter, as the following example shows:

如果您需要访问预先存在的全局管理的（即，在控制器之外 —— 例如，过滤器管理？）会话属性，并且可能存在或不存在，您可以在方法参数上使用@SessionAttribute注解，如下所示示例显示：

@GetMapping("/")
public String handle(@SessionAttribute User user) { //(1)
    // ...
}

(1) Using @SessionAttribute.

For use cases that require adding or removing session attributes, consider injecting WebSession into the controller method.

对于需要添加或删除会话属性的用例，请考虑向控制器方法注入 WebSession。

For temporary storage of model attributes in the session as part of a controller workflow, consider using SessionAttributes, as described in @SessionAttributes.

对于作为控制器工作流的一部分的会话模型属性的临时存储，请考虑使用SessionAttributes，如 @SessionAttributes中所述。

@RequestAttribute

Similarly to @SessionAttribute, you can use the @RequestAttribute annotation to access pre-existing request attributes created earlier (for example, by a WebFilter), as the following example shows:

与@SessionAttribute类似，您可以使用@RequestAttribute注解来访问先前创建的预先存在的请求属性（例如，通过WebFilter），如以下示例所示：

@GetMapping("/")
public String handle(@RequestAttribute Client client) { //(1)
    // ...
}

(1) Using @RequestAttribute.

Multipart Content 【多部分内容】

As explained in Multipart Data, ServerWebExchange provides access to multipart content. The best way to handle a file upload form (for example, from a browser) in a controller is through data binding to a command object, as the following example shows:

如Multipart Data中所述，ServerWebExchange提供对多部分内容的访问。在控制器中处理文件上传表单（例如，来自浏览器）的最佳方法是通过数据绑定到命令对象，如以下示例所示：

class MyForm {
    private String name;
    private MultipartFile file;
    // ...
}

@Controller
public class FileUploadController {

    @PostMapping("/form")
    public String handleFormUpload(MyForm form, BindingResult errors) {
        // ...
    }

}

You can also submit multipart requests from non-browser clients in a RESTful service scenario. The following example uses a file along with JSON:

您还可以在 RESTful 服务场景中提交来自非浏览器客户端的多部分请求。以下示例使用文件和 JSON：

POST /someUrl
Content-Type: multipart/mixed

--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; 
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
    "name": "value"
}
--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; 
Content-Type: text/xml
Content-Transfer-Encoding: 8bit
... File Data ...

You can access individual parts with @RequestPart, as the following example shows:

您可以使用@RequestPart访问各个部分，如下例所示：

@PostMapping("/")
public String handle(@RequestPart("meta-data") Part metadata, //(1)
        @RequestPart("file-data") FilePart file) { //(2)
    // ...
}

(1) Using @RequestPart to get the metadata.
(2) Using @RequestPart to get the file.

(1) 使用@RequestPart获得元数据。
(2) 使用@RequestPart来获取文件。

To deserialize the raw part content (for example, to JSON — similar to @RequestBody), you can declare a concrete target Object, instead of Part, as the following example shows:

要反序列化原始部分内容（例如，对于JSON — 类似于@RequestBody），您可以声明一个具体的 target Object，而不是Part，如以下示例所示：

@PostMapping("/")
public String handle(@RequestPart("meta-data") MetaData metadata) { //(1)
    // ...
}

(1) Using @RequestPart to get the metadata.

You can use @RequestPart in combination with javax.validation.Valid or Spring’s @Validated annotation, which causes Standard Bean Validation to be applied. Validation errors lead to a WebExchangeBindException that results in a 400 (BAD_REQUEST) response. The exception contains a BindingResult with the error details and can also be handled in the controller method by declaring the argument with an async wrapper and then using error related operators:

您可以将@RequestPart与javax.validation.Valid或 Spring 的 @Validated注解结合使用，这样就会应用标准 Bean 验证。验证错误会引发一个WebExchangeBindException从而导致一个400 (BAD_REQUEST) 响应。异常包含一个有错误详细信息的BindingResult，这也可以通过在控制器方法中声明使用异步包装器的参数然后使用与错误相关的运算符来处理：

@PostMapping("/")
public String handle(@Valid @RequestPart("meta-data") Mono<MetaData> metadata) {
    // ...
}

To access all multipart data as a MultiValueMap, you can use @RequestBody, as the following example shows:

要将所有多部分数据作为MultiValueMap访问，您可以使用@RequestBody，如下例所示：

@PostMapping("/")
public String handle(@RequestBody Mono<MultiValueMap<String, Part>> parts) { //(1)
    // ...
}

(1) Using @RequestBody.

To access multipart data sequentially, in streaming fashion, you can use @RequestBody with Flux<Part> (or Flow<Part> in Kotlin) instead, as the following example shows:

要以流的方式顺序地访问多部分数据，您可以使用@RequestBody搭配 Flux<Part>（或搭配Flow<Part>在 Kotlin 中），如下例所示：

@PostMapping("/")
public String handle(@RequestBody Flux<Part> parts) { (1)
    // ...
}

(1) Using @RequestBody.

@RequestBody

You can use the @RequestBody annotation to have the request body read and deserialized into an Object through an HttpMessageReader. The following example uses a @RequestBody argument:

您可以使用@RequestBody注解读取请求体并通过HttpMessageReader反序列化到一个Object。以下示例使用@RequestBody参数：

@PostMapping("/accounts")
public void handle(@RequestBody Account account) {
    // ...
}

Unlike Spring MVC, in WebFlux, the @RequestBody method argument supports reactive types and fully non-blocking reading and (client-to-server) streaming.

与 Spring MVC 不同，在 WebFlux 中，@RequestBody方法参数支持响应式类型和完全非阻塞读取以及（客户端到服务器）流。

@PostMapping("/accounts")
public void handle(@RequestBody Mono<Account> account) {
    // ...
}

You can use @RequestBody in combination with javax.validation.Valid or Spring’s @Validated annotation, which causes Standard Bean Validation to be applied. Validation errors cause a WebExchangeBindException, which results in a 400 (BAD_REQUEST) response. The exception contains a BindingResult with error details and can be handled in the controller method by declaring the argument with an async wrapper and then using error related operators:

您可以将@RequestBody与javax.validation.Valid或 Spring 的 @Validated注解结合使用，这样就会应用标准 Bean 验证。验证错误会引发一个WebExchangeBindException从而导致一个400 (BAD_REQUEST) 响应。异常包含一个有错误详细信息的BindingResult，这也可以通过在控制器方法中声明使用异步包装器的参数然后使用与错误相关的运算符来处理：

@PostMapping("/accounts")
public void handle(@Valid @RequestBody Mono<Account> account) {
    // ...
}

HttpEntity

HttpEntity is more or less identical to using @RequestBody but is based on a container object that exposes request headers and the body. The following example uses an HttpEntity:

HttpEntity与@RequestBody的使用或多或少是相同的，但它基于公开/暴露请求头和请求体的容器对象。以下示例使用 HttpEntity：

@PostMapping("/accounts")
public void handle(HttpEntity<Account> entity) {
    // ...
}

@ResponseBody

You can use the @ResponseBody annotation on a method to have the return serialized to the response body through an HttpMessageWriter. The following example shows how to do so:

您可以在方法上使用@ResponseBody注解，以通过一个HttpMessageWriter将返回值序列化为响应正文。以下示例显示了如何执行此操作：

@GetMapping("/accounts/{id}")
@ResponseBody
public Account handle() {
    // ...
}

@ResponseBody is also supported at the class level, in which case it is inherited by all controller methods. This is the effect of @RestController, which is nothing more than a meta-annotation marked with @Controller and @ResponseBody.

@ResponseBody在类级别也受支持，在这种情况下，所有控制器方法都会继承它。@RestController的效果无非是一个用@Controller和@ResponseBody标记的元注解(@RestController实际是@Controller和@ResponseBody组合而成)。

@ResponseBody supports reactive types, which means you can return Reactor or RxJava types and have the asynchronous values they produce rendered to the response. For additional details, see Streaming and JSON rendering.

@ResponseBody支持响应式类型，这意味着您可以返回 Reactor 或 RxJava 类型，并将它们产生的异步值呈现给响应。有关其他详细信息，请参阅流式处理和 JSON 渲染。

You can combine @ResponseBody methods with JSON serialization views. See Jackson JSON for details.

您可以将@ResponseBody方法与 JSON 序列化视图结合使用。有关详细信息，请参阅Jackson JSON。

ResponseEntity

ResponseEntity is like @ResponseBody but with status and headers. For example:

ResponseEntity就像@ResponseBody，但它有状态和头信息。例如：

@GetMapping("/something")
public ResponseEntity<String> handle() {
    String body = ... ;
    String etag = ... ;
    return ResponseEntity.ok().eTag(etag).build(body);
}

WebFlux supports using a single value reactive type to produce the ResponseEntity asynchronously, and/or single and multi-value reactive types for the body. This allows a variety of async responses with ResponseEntity as follows:

WebFlux支持使用单值的反应式类型，来异步地生成ResponseEntity，和/或生成单值和多值的反应式类型的正文。这允许各种异步ResponseEntity响应如下：

• ResponseEntity<Mono<T>> or ResponseEntity<Flux<T>> make the response status and headers known immediately while the body is provided asynchronously at a later point. Use Mono if the body consists of 0..1 values or Flux if it can produce multiple values.
• ResponseEntity<Mono<T>>或ResponseEntity<Flux<T>>使得在之后正文被异步提供时能够立即知道响应状态和头信息。如果正文是0~1个值则使用Mono，如果是多个值则使用Flux。
• Mono<ResponseEntity<T>> provides all three — response status, headers, and body, asynchronously at a later point. This allows the response status and headers to vary depending on the outcome of asynchronous request handling.
• Mono<ResponseEntity<T>>提供响应的所有三个部分 - 响应状态、头信息和正文，稍后以异步方式提供。这允许响应状态和头信息根据异步请求处理的结果而变化。
• Mono<ResponseEntity<Mono<T>>> or Mono<ResponseEntity<Flux<T>>> are yet another possible, albeit less common alternative. They provide the response status and headers asynchronously first and then the response body, also asynchronously, second.
• Mono<ResponseEntity<Mono<T>>>或者Mono<ResponseEntity<Flux<T>>>是另一种可能选择，尽管不太常见。它们首先异步提供响应状态和头信息，然后提供响应体，同样也是异步的。

Jackson JSON

Spring offers support for the Jackson JSON library.

Spring 提供对 Jackson JSON 库的支持。

JSON Views 【JSON 视图】

Spring WebFlux provides built-in support for Jackson’s Serialization Views, which allows rendering only a subset of all fields in an Object. To use it with @ResponseBody or ResponseEntity controller methods, you can use Jackson’s @JsonView annotation to activate a serialization view class, as the following example shows:

Spring WebFlux 为Jackson 的序列化视图提供了内置支持 ，它允许只渲染一个Object中所有字段的子集。要将其与 @ResponseBody或ResponseEntity控制器方法一起使用，您可以使用 Jackson 的 @JsonView注解来激活序列化视图类，如下例所示：

@RestController
public class UserController {

    @GetMapping("/user")
    @JsonView(User.WithoutPasswordView.class)
    public User getUser() {
        return new User("eric", "7!jd#h23");
    }
}

public class User {

    public interface WithoutPasswordView {};
    public interface WithPasswordView extends WithoutPasswordView {};

    private String username;
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    @JsonView(WithoutPasswordView.class)
    public String getUsername() {
        return this.username;
    }

    @JsonView(WithPasswordView.class)
    public String getPassword() {
        return this.password;
    }
}

@JsonView allows an array of view classes but you can only specify only one per controller method. Use a composite interface if you need to activate multiple views.

@JsonView允许一组视图类，但您只能为每个控制器方法指定一个@JsonView 。如果您需要激活多个视图，请使用复合界面。

1.4.4. Model

You can use the @ModelAttribute annotation:

您可以使用@ModelAttribute注解：

• On a method argument in @RequestMapping methods to create or access an Object from the model and to bind it to the request through a WebDataBinder.

• 在@RequestMapping注解方法的方法参数上创建或访问模型中的对象，并通过WebDataBinder将其绑定到请求上。

• As a method-level annotation in @Controller or @ControllerAdvice classes, helping to initialize the model prior to any @RequestMapping method invocation.

• 作为@Controller或@ControllerAdvice类中的方法级注解，帮助在任何@RequestMapping方法调用之前初始化模型。

• On a @RequestMapping method to mark its return value as a model attribute.

• 在一个@RequestMapping方法上，将其返回值标记为模型属性。

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方法，或前面列表中的第二项。一个控制器可以有任意数量的@ModelAttribute方法。所有这些方法都先于同一控制器中的@RequestMapping方法之前调用。@ModelAttribute 方法还可以通过@ControllerAdvice跨控制器共享。有关更多详细信息，请参阅控制器建议部分 。

@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).

@ModelAttribute方法具有灵活的方法签名。它们支持许多与@RequestMapping方法相同的参数（除了@ModelAttribute自身及与请求正文相关的内容）。

The following example uses a @ModelAttribute method:

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

@ModelAttribute
public void populateModel(@RequestParam String number, Model model) {
    model.addAttribute(accountRepository.findAccount(number));
    // add more ...
}

The following example adds one attribute only:

以下示例仅添加一个属性：

@ModelAttribute
public Account addAccount(@RequestParam String number) {
    return accountRepository.findAccount(number);
}

When a name is not explicitly specified, a default name is chosen based on the type, as explained in the javadoc for onventions. You can always assign an explicit name by using the overloaded addAttribute method or through the name attribute on @ModelAttribute (for a return value).

如果未明确指定名称，则会根据类型选择默认名称，如onventions所述。您始终可以通过使用重载的ddAttribute方法或通过ModelAttribute上的名称属性(用于返回值）来分配明确的名称。

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:

与 Spring MVC 不同，Spring WebFlux 明确/显式支持模型中的反应式类型（例如，Mono<Account>or io.reactivex.Single<Account>）。这种异步模型属性可以在@RequestMapping调用时透明地解析（并更新模型）为其实际值，前提是@ModelAttribute参数是在没有包装器的情况下声明的，如以下示例所示：

@ModelAttribute
public void addAccount(@RequestParam String number) {
    Mono<Account> accountMono = accountRepository.findAccount(number);
    model.addAttribute("account", accountMono);
}

@PostMapping("/accounts")
public String handle(@ModelAttribute Account account, BindingResult errors) {
    // ...
}

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:

您还可以在@RequestMapping方法上将@ModelAttribute用作方法级注解，在这种情况下，@RequestMapping方法的返回值被解析为模型属性。这通常不是必需的，因为它是 HTML 控制器中的默认行为，除非返回值是String(则会被解析为视图名称)。@ModelAttribute还可以帮助自定义模型属性名称，如下例所示：

@GetMapping("/accounts/{id}")
@ModelAttribute("myAccount")
public Account handle() {
    // ...
    return account;
}

1.4.5. DataBinder

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

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

• Bind request parameters (that is, form data or query) to a model object.

• 将请求参数（即表单数据或查询）绑定到模型对象。

• Convert String-based request values (such as request parameters, path variables, headers, cookies, and others) to the target type of controller method arguments.

• 将String类的请求值（例如请求参数、路径变量、头信息、cookie 等）转换为控制器方法参数的目标类型。

• Format model object values as String values when rendering HTML forms.

• 当渲染 HTML 表单时将模型对象值格式化为String值。

@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方法可以注册特定于控制器的java.beans.PropertyEditor或 Spring Converter和Formatter组件。此外，您可以使用 WebFlux Java配置在全局共享FormattingConversionService中注册Converter和 Formatter类型。

@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:

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

@Controller
public class FormController {
    @InitBinder //(1)
    public void initBinder(WebDataBinder binder) {
        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        dateFormat.setLenient(false);
        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false));
    }
    // ...
}

(1) Using the InitBinderannotation.

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:

或者，当通过共享的FormattingConversionService使用基于Formatter的设置时，您可以重用相同的方式并注册特定于控制器的Formatter实例，如以下示例所示：

@Controller
public class FormController {
    @InitBinder
    protected void initBinder(WebDataBinder binder) {
        binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); //(1)
    }
	// ...
}

(1) Adding a custom formatter (a DateFormatter, in this case).

(1) 添加自定义格式化程序（在本例中是一个 DateFormatter）。

1.4.6. Managing Exceptions 【管理异常】

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

@Controller和@ControllerAdvice类可以有 @ExceptionHandler方法来处理来自控制器方法的异常。以下示例包括这样的处理程序方法：

@Controller
public class SimpleController {
    // ...
    @ExceptionHandler //(1)
    public ResponseEntity<String> handle(IOException ex) {
        // ...
    }
}

(1) Declaring an @ExceptionHandler.

(1) 声明一个@ExceptionHandler.

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).

异常可以与正在传播的顶级异常（直接抛出的IOException）匹配，也可以与顶级包装器异常（例如，一个IOException包裹在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.

为了匹配异常类型，最好将目标异常声明为方法参数，如前例所示。或者，注解声明可以缩小要匹配的异常类型。我们通常建议在参数签名中尽可能具体，并在@ControllerAdvice上声明主根异常映射，并按相应顺序排列优先级。有关详细信息，请参阅MVC 部分。

An @ExceptionHandler method in WebFlux supports the same method arguments and return values as a @RequestMapping method, with the exception of request body- and @ModelAttribute-related method arguments.

WebFlux 中的@ExceptionHandler方法支持与@RequestMapping方法相同的方法参数和返回值，除了请求主体相关和@ModelAttribute相关的方法参数外。

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

在Spring WebFlux中，@ExceptionHandler方法的支持由@RequestMapping方法的HandlerAdapter提供。请参阅DispatcherHandler 了解更多详情。

REST API exceptions 【REST API 异常】

A common requirement for REST services is to include error details in the body of the response. The Spring Framework does not automatically do so, because the representation of error details in the response body is application-specific. However, a @RestController can use @ExceptionHandler methods with a ResponseEntity return value to set the status and the body of the response. Such methods can also be declared in @ControllerAdvice classes to apply them globally.

REST 服务的一个常见要求是在响应正文中包含错误详细信息。Spring Framework 不会自动这样做，因为响应正文中错误详细信息的表示是特定于应用程序的。但是，a @RestController可以使用@ExceptionHandler带有ResponseEntity返回值的方法来设置响应的状态和正文。这些方法也可以在@ControllerAdvice类中声明以全局应用它们。

Note that Spring WebFlux does not have an equivalent for the Spring MVC ResponseEntityExceptionHandler, because WebFlux raises only ResponseStatusException (or subclasses thereof), and those do not need to be translated to an HTTP status code.

请注意，Spring WebFlux 没有 Spring MVC 的等效项 ResponseEntityExceptionHandler，因为 WebFlux 仅引发ResponseStatusException （或其子类），并且不需要将其转换为 HTTP 状态代码。

1.4.7. Controller Advice 【控制器建议】

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.

一般，@ExceptionHandler，@InitBinder，和@ModelAttribute方法在@Controller注解的类（或类级别）中声明并应用。如果您希望这些方法在全局范围内（跨控制器）应用，您可以在用@ControllerAdvice或@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).

@ControllerAdvice被@Component注解，这意味着这些类可以通过组件扫描注册为Spring bean 。@RestControllerAdvice是一个同时被@ControllerAdvice和@ResponseBody注解的组合注解，这实质上意味着@ExceptionHandler方法是通过消息转换（相对于视图解析或模板渲染）被渲染到响应体。

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.

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

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:

默认情况下，@ControllerAdvice方法适用于每个请求（即所有控制器），但您可以通过使用注解上的属性将其缩小到控制器的子集，如以下示例所示：

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)
public class ExampleAdvice1 {}

// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
public class ExampleAdvice2 {}

// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})
public class ExampleAdvice3 {}

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

前面示例中的选择器是在运行时进行评估的，如果广泛使用，可能会对性能产生负面影响。有关@ControllerAdvice 更多详细信息，请参阅 javadoc。

1.5. Functional Endpoints 【函数式端点】

Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on the same Reactive Core foundation.

Spring WebFlux 包括 WebFlux.fn，这是一个轻量级的函数式编程模型，其中函数用于路由和处理请求，契约旨在实现不变性。它是基于注解的编程模型的替代方案，但在相同的Reactive Core基础上运行。

1.5.1. Overview 【概述】

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.

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

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.

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

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

RouterFunctions.route() 提供了一个帮助创建router的router构建器，如以下示例所示：

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()
    .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) {
        // ...
    }
}

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

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

• RouterFunctions.toHttpHandler(RouterFunction)

• RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)

Most applications can run through the WebFlux Java configuration, see Running a Server.

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

1.5.2. HandlerFunction 【 处理函数】

ServerRequest and ServerResponse are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response. Both request and response provide Reactive Streams back pressure against the body streams. The request body is represented with a Reactor Flux or Mono. The response body is represented with any Reactive Streams Publisher, including Flux and Mono. For more on that, see Reactive Libraries.

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

ServerRequest 【服务器请求】

ServerRequest provides access to the HTTP method, URI, headers, and query parameters, while access to the body is provided through the body methods.

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

The following example extracts the request body to a Mono<String>:

以下示例将请求正文提取到一个Mono<String>：

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

The following example extracts the body to a Flux<Person> (or a Flow<Person> in Kotlin), where Person objects are decoded from someserialized form, such as JSON or XML:

以下示例将请求正文提取到一个Flux<Person>（或Kotlin 中的Flow<Person>），其中Person对象以某种序列化形式（例如 JSON 或 XML ）中解码：

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

The preceding examples are shortcuts that use the more general ServerRequest.body(BodyExtractor), which accepts the BodyExtractor functional strategy interface. The utility class BodyExtractors provides access to a number of instances. For example, the preceding examples can also be written as follows:

前面的示例是使用更通用的ServerRequest.body(BodyExtractor)的一种快捷方式，它接受BodyExtractor功能策略接口。实用程序类 BodyExtractors提供对许多实例的访问。例如，前面的例子也可以写成这样：

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

The following example shows how to access form data:

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

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

The following example shows how to access multipart data as a map:

以下示例显示如何将多部分数据作为映射访问：

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

The following example shows how to access multiparts, one at a time, in streaming fashion:

以下示例显示了如何以流方式一次一个地访问多部分：

Flux<Part> parts = request.body(BodyExtractors.toParts());

ServerResponse 【服务器响应】

ServerResponse provides access to the HTTP response and, since it is immutable, you can use a build method to create it. You can use the builder to set the response status, to add response headers, or to provide a body. The following example creates a 200 (OK) response with JSON content:

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

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

The following example shows how to build a 201 (CREATED) response with a Location header and no body:

以下示例显示了如何构建带有Location标头但没有正文的 201 (CREATED) 响应：

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

Depending on the codec used, it is possible to pass hint parameters to customize how the body is serialized or deserialized. For example, to specify a Jackson JSON view:

根据所使用的编解码器，可以通过传递提示参数来自定义正文的序列化或反序列化方式。例如，要指定Jackson JSON 视图：

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

Handler Classes 【处理器类】

We can write a handler function as a lambda, as the following example shows:

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

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

That is convenient, but in an application we need multiple functions, and multiple inline lambda’s can get messy. Therefore, it is useful to group related handler functions together into a handler class, which has a similar role as @Controller in an annotation-based application. For example, the following class exposes a reactive Person repository:

这很方便，但在应用程序中我们需要多个函数，而多个内联 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());
    }
}

(1) listPeople is a handler function that returns all Person objects found in the repository as JSON.
(2) createPerson is a handler function that stores a new Person contained in the request body. Note that PersonRepository.savePerson(Person) returns Mono<Void>: an empty Mono that emits a completion signal when the person has been read from the request and stored. So we use the build(Publisher<Void>) method to send a response when that completion signal is received (that is, when the Person has been saved).
(3) getPerson is a handler function that returns a single person, identified by the id path
variable. We retrieve that Person from the repository and create a JSON response, if it is
found. If it is not found, we use switchIfEmpty(Mono<T>) to return a 404 Not Found response.

(1) listPeople是一个处理函数，它将Person存储库中找到的所有对象作为 JSON 返回。
(2) createPerson是一个处理程序函数，用于存储Person请求正文中包含的新内容。请注意，PersonRepository.savePerson(Person)返回Mono<Void>: 一个空的Mono(当从请求中读取person并存储完时，它会发出完成信号)。因此，我们使用build(Publisher<Void>)方法(在收到完成信号时（即Person已保存时）)发送响应。
(2) getPerson是一个处理函数，它返回一个person，由id路径变量标识。我们从存储库中检索Person并创建一个 JSON 响应（如果找到）。如果未找到，我们使用switchIfEmpty(Mono<T>)返回 404 Not Found 响应。

Validation 【验证】

A functional endpoint can use Spring’s validation facilities to apply validation to the request body. For example, given a custom Spring Validator implementation for a Person:

函数式端点可以使用 Spring 的验证工具验证请求正文。例如，给Person一个自定义 Spring Validator实现：

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)
        }
    }
}

(1) Create Validator instance.
(2) Apply validation.
(3) Raise exception for a 400 response.

(1) 创建Validator实例。
(2) 应用验证。
(3) 引发 400 响应的异常。

Handlers can also use the standard bean validation API (JSR-303) by creating and injecting a global Validator instance based on LocalValidatorFactoryBean. See Spring Validation.

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

1.5.3. RouterFunction 【路由函数】

Router functions are used to route the requests to the corresponding HandlerFunction. Typically, you do not write router functions yourself, but rather use a method on the RouterFunctions utility class to create one. RouterFunctions.route() (no parameters) provides you with a fluent builder for creating a router function, whereas RouterFunctions.route(RequestPredicate, HandlerFunction) offers a direct way to create a router.

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

Generally, it is recommended to use the route() builder, as it provides convenient short-cuts for typical mapping scenarios without requiring hard-to-discover static imports. For instance, the router function builder offers the method GET(String, HandlerFunction) to create a mapping for GET requests; and POST(String, HandlerFunction) for POSTs.

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

Besides HTTP method-based mapping, the route builder offers a way to introduce additional predicates when mapping to requests. For each HTTP method there is an overloaded variant that takes a RequestPredicate as a parameter, though which additional constraints can be expressed.

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

Predicates 【谓语】

You can write your own RequestPredicate, but the RequestPredicates utility class offers commonly used implementations, based on the request path, HTTP method, content-type, and so on. The following example uses a request predicate to create a constraint based on the Accept header:

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

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

You can compose multiple request predicates together by using:

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

• RequestPredicate.and(RequestPredicate) — both must match. —— 两者必须匹配

• RequestPredicate.or(RequestPredicate) — either can match. —— 任一个都可以匹配

Many of the predicates from RequestPredicates are composed. For example, RequestPredicates.GET(String) is composed from RequestPredicates.method(HttpMethod) and RequestPredicates.path(String). The example shown above also uses two request predicates, as the builder uses RequestPredicates.GET internally, and composes that with the accept predicate.

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

Routes 【路由】

Router functions are evaluated in order: if the first route does not match, the second is evaluated, and so on. Therefore, it makes sense to declare more specific routes before general ones. This is also important when registering router functions as Spring beans, as will be described later. Note that this behavior is different from the annotation-based programming model, where the "most specific" controller method is picked automatically.

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

When using the router function builder, all defined routes are composed into one RouterFunction that is returned from build(). There are also other ways to compose multiple router functions together:

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

• add(RouterFunction) on the RouterFunctions.route() builder

• RouterFunction.and(RouterFunction)

• RouterFunction.andRoute(RequestPredicate, HandlerFunction) — shortcut for RouterFunction.and() with nested(嵌套) RouterFunctions.route().

The following example shows the composition of four routes:

下面的例子展示了四个路由的组合：

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();

(1) GET /person/{id} with an Accept header that matches JSON is routed to PersonHandler.getPerson
(2) GET /person with an Accept header that matches JSON is routed to PersonHandler.listPeople
(3) POST /person with no additional predicates is mapped to PersonHandler.createPerson, and
(4) otherRoute is a router function that is created elsewhere, and added to the route built.

(1)与 GET /person/{id}与Accept 头匹配的JSON被路由到PersonHandler.getPerson
(2) 与GET /person与Acqcept 头匹配的JSON被路由到PersonHandler.listPeople
(3) 与POST /personq且没有额外的谓词匹配，被映射到PersonHandler.createPerson
(4) otherRoute 是在别处创建的路由函数，并添加到构建的路由中。

Nested Routes 【嵌套路由】

It is common for a group of router functions to have a shared predicate, for instance a shared path. In the example above, the shared predicate would be a path predicate that matches /person, used by three of the routes. When using annotations, you would remove this duplication by using a type-level @RequestMapping annotation that maps to /person. In WebFlux.fn, path predicates can be shared through the path method on the router function builder. For instance, the last few lines of the example above can be improved in the following way by using nested routes:

通常，一组路由器函数具有共享的谓词，例如共享路径。在上面的例子中，共享谓词是一个匹配/person路径的谓词，由三个路由使用。使用注解时，您将通过在类上使用@RequestMapping注解映射到 /person来消除此种重复。在 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("/person", handler::createPerson))
    .build();

(1) Note that second parameter of path is a consumer that takes the a router builder.

(1) 请注意，path方法的第二个参数是使用路由器构建器的消费者。

Though path-based nesting is the most common, you can nest on any kind of predicate by using the nest method on the builder. The above still contains some duplication in the form of the shared Accept-header predicate. We can further improve by using the nest method together with accept:

尽管基于路径的嵌套是最常见的，但您可以使用构建器上的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("/person", handler::createPerson))
    .build();

1.5.4. Running a Server 【 运行服务器】

How do you run a router function in an HTTP server? A simple option is to convert a router function to an HttpHandler by using one of the following:

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

• RouterFunctions.toHttpHandler(RouterFunction)

• RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)

You can then use the returned HttpHandler with a number of server adapters by following HttpHandler for server-specific instructions.

之后，您可以按照特定于服务器的HttpHandler说明来使用返回的HttpHandler(with一些server适配器) 。

A more typical option, also used by Spring Boot, is to run with a DispatcherHandler-based setup through the WebFlux Config, which uses Spring configuration to declare the components required to process requests. The WebFlux Java configuration declares the following infrastructure components to support functional endpoints:

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

• RouterFunctionMapping: Detects one or more RouterFunction<?> beans in the Spring configuration, orders them, combines them through RouterFunction.andOther, and routes requests to the resulting composed RouterFunction.

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

• HandlerFunctionAdapter: Simple adapter that lets DispatcherHandler invoke a HandlerFunction that was mapped to a request.

• HandlerFunctionAdapter：允许DispatcherHandler调用HandlerFunction(映射到对应请求)的简单适配器。

• ServerResponseResultHandler: Handles the result from the invocation of a HandlerFunction by invoking the writeTo method of the ServerResponse.

• ServerResponseResultHandler:处理来自调用HandlerFunction（通过调用ServerResponse的writeTo方法）的结果。

The preceding components let functional endpoints fit within the DispatcherHandler request processing lifecycle and also (potentially) run side by side with annotated controllers, if any are declared. It is also how functional endpoints are enabled by the Spring Boot WebFlux starter.

前面的组件让函数式端点适合DispatcherHandler请求处理生命周期，并且（可能）与带注解的控制器一起生效/运行(如果有声明的话)。这也是在 Spring Boot WebFlux starter 启用功能端点的方式。

The following example shows a WebFlux Java configuration (see DispatcherHandler for how to run it):

以下示例显示了 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...
    }
}

1.5.5. Filtering Handler Functions 【过滤处理函数】

You can filter handler functions by using the before, after, or filter methods on the routing function builder. With annotations, you can achieve similar functionality by using @ControllerAdvice, a ServletFilter, or both. The filter will apply to all routes that are built by the builder. This means that filters defined in nested routes do not apply to "top-level" routes. For instance, consider the following example:

您可以通过在路由功能生成器上使用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("/person", handler::createPerson))
    .after((request, response) -> logResponse(response)) //(2)
    .build();

(1) The before filter that adds a custom request header is only applied to the two GET routes.
(2) The after filter that logs the response is applied to all routes, including the nested ones.

(1) before过滤器添加的自定义请求头仅用于两个 GET 路由。
(1) after过滤器记录响应的操作适用于所有路由，包括嵌套路由。

The filter method on the router builder takes a HandlerFilterFunction: a function that takes a ServerRequest and HandlerFunction and returns a ServerResponse. The handler function parameter represents the next element in the chain. This is typically the handler that is routed to, but it can also be another filter if multiple are applied.

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

Now we can add a simple security filter to our route, assuming that we have a SecurityManager that can determine whether a particular path is allowed. The following example shows how to do so:

现在我们可以向我们的路由添加一个简单的安全过滤器，假设我们有一个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("/person", handler::createPerson))
    .filter((request, next) -> {
        if (securityManager.allowAccessTo(request.path())) {
            return next.handle(request);
        }
        else {
            return ServerResponse.status(UNAUTHORIZED).build();
        }
    })
    .build();

The preceding example demonstrates that invoking the next.handle(ServerRequest) is optional. We only let the handler function be run when access is allowed.

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

Besides using the filter method on the router function builder, it is possible to apply a filter to an existing router function via RouterFunction.filter(HandlerFilterFunction).

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

CORS support for functional endpoints is provided through a dedicated CorsWebFilter.

对函数式端点的 CORS 支持是通过专用的 CorsWebFilter 提供的。

1.6. URI Links 【URI 链接】

This section describes various options available in the Spring Framework to prepare URIs.

本节介绍 Spring Framework 中可用于准备 URI 的各种选项。

1.6.1. UriComponents 【URI 组件】

Spring MVC and Spring WebFlux

UriComponentsBuilder helps to build URI’s from URI templates with variables, as the following example shows:

UriComponentsBuilder 用于从带有变量的 URI 模板来构建 URI，如以下示例所示：

补充：

• URI 模板是一个像URI的字符串，它包含一个或多个变量名。当你用值来替代这些变量时，这个模板就会变成一个 URI。、Or
• URI 和 URL 有什么区别？

UriComponents uriComponents = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")  //(1)
        .queryParam("q", "{q}")  //(2)
        .encode() //(3)
        .build(); //(4)

URI uri = uriComponents.expand("Westin", "123").toUri();  //(5)

(1) Static factory method with a URI template.
(2) Add or replace URI components.
(3) Request to have the URI template and URI variables encoded.
(4) Build a UriComponents.
(5) Expand variables and obtain the URI.

(1) 带有 URI 模板的静态工厂方法。
(2) 添加或替换 URI 组件。
(3) 请求对 URI 模板和 URI 变量进行编码。
(4) 构建一个UriComponents.
(5) 展开变量并获得URI.

The preceding example can be consolidated into one chain and shortened with buildAndExpand, as the following example shows:

可以将前面的示例合并为一个链，并使用buildAndExpand来缩短，如下例所示：

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri();

You can shorten it further by going directly to a URI (which implies encoding), as the following example shows:

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

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

You can shorten it further still with a full URI template, as the following example shows:

您也可以使用完整的 URI 模板进一步缩短它，如以下示例所示：

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123");

1.6.2. UriBuilder

Spring MVC and Spring WebFlux

UriComponentsBuilder implements UriBuilder. You can create a UriBuilder, in turn, with a UriBuilderFactory. Together, UriBuilderFactory and UriBuilder provide a pluggable mechanism to build URIs from URI templates, based on shared configuration, such as a base URL, encoding preferences, and other details.

UriComponentsBuilder实现自UriBuilder。您可以用UriBuilderFactory依次创建一个UriBuilder。UriBuilderFactory和UriBuilder 一起提供可插拔地从 URI 模板构建 URI(基于共享配置（例如基础 URL、编码首选项和其他细节）)。

补充：

• URI 模板是一个像URI的字符串，它包含一个或多个变量名。当你用值来替代这些变量时，这个模板就会变成一个 URI。、Or
• URI 和 URL 有什么区别？

You can configure RestTemplate and WebClient with a UriBuilderFactory to customize the preparation of URIs. DefaultUriBuilderFactory is a default implementation of UriBuilderFactory that uses UriComponentsBuilder internally and exposes shared configuration options.

您可以通过使用UriBuilderFactory 配置RestTemplate和WebClient来自定义 URI 的准备。DefaultUriBuilderFactory(内部使用UriComponentsBuilder并公开/暴露共享配置选项)是UriBuilderFactory的默认实现。

The following example shows how to configure a RestTemplate:

以下示例显示了如何配置一个RestTemplate：

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

The following example configures a WebClient:

以下示例配置了一个WebClient：

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

In addition, you can also use DefaultUriBuilderFactory directly. It is similar to using UriComponentsBuilder but, instead of static factory methods, it is an actual instance that holds configuration and preferences, as the following example shows:

此外，你也可以直接使用DefaultUriBuilderFactory。类似于使用UriComponentsBuilder，但它不是静态工厂方法，而是一个包含配置和首选项的真实实例，如以下示例所示：

String baseUrl = "https://example.com";
DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);

URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

1.6.3. URI Encoding 【URI 编码】

Spring MVC and Spring WebFlux

UriComponentsBuilder exposes encoding options at two levels:

UriComponentsBuilder 公开/暴露两个级别的编码选项：

• UriComponentsBuilder#encode(): Pre-encodes the URI template first and then strictly encodes URI variables when expanded.

• UriComponentsBuilder#encode()：首先对 URI 模板进行预编码，然后在展开时(指将uri中变量等占位符替换为实际值等操作)对 URI 变量进行严格编码。

• UriComponents#encode(): Encodes URI components after URI variables are expanded.

• UriComponents#encode()：在展开 URI 变量后对URI 组件进行编码。

Both options replace non-ASCII and illegal characters with escaped octets. However, the first option also replaces characters with reserved meaning that appear in URI variables.

这两种方式都用转义字符替换非 ASCII 码字符 和非法字符。但是，第一种方式还会替换 URI 变量中具有保留含义的字符。

Consider ";", which is legal in a path but has reserved meaning. The first option replaces ";" with "%3B" in URI variables but not in the URI template. By contrast, the second option never replaces ";", since it is a legal character in a path.

考虑“;”，它在路径中是合法的，但具有保留含义。第一种方式会用“%3B”替换URI 变量中的“;” 而不会替换 URI 模板中的“;”。相比之下，第二个选项永远不会替换“;”，因为它是路径中的合法字符。

For most cases, the first option is likely to give the expected result, because it treats URI variables as opaque data to be fully encoded, while the second option is useful if URI variables do intentionally contain reserved characters. The second option is also useful when not expanding URI variables at all since that will also encode anything that incidentally looks like a URI variable.

在大多数情况下，第一种方式可能会给出预期的结果，因为它将 URI 变量视为要完全编码的不透明数据，而如果 URI 变量有意包含保留字符，则第二种方式很有用。当根本不展开 URI 变量时，第二种方式也很有用，因为它也可以对任何看起来像 URI 变量的东西进行编码。

The following example uses the first option:

以下示例使用第一个选项：

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("New York", "foo+bar")
        .toUri();
// Result is "/hotel%20list/New%20York?q=foo%2Bbar"

You can shorten the preceding example by going directly to the URI (which implies encoding), as the following example shows:

您可以通过直接获得 URI（这意味着编码）来缩短前面的示例，如以下示例所示：

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .build("New York", "foo+bar");

You can shorten it further still with a full URI template, as the following example shows:

您还可以通过使用完整的 URI 模板进一步缩短它，如以下示例所示：

URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
        .build("New York", "foo+bar");

The WebClient and the RestTemplate expand and encode URI templates internally through the UriBuilderFactory strategy. Both can be configured with a custom strategy, as the following example shows:

WebClient和RestTemplate内部展开和编码URI模板是使用UriBuilderFactory策略。两者都可以配置使用自定义策略，如以下示例所示：

String baseUrl = "https://example.com";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

// Customize the RestTemplate..
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

// Customize the WebClient..
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

The DefaultUriBuilderFactory implementation uses UriComponentsBuilder internally to expand and encode URI templates. As a factory, it provides a single place to configure the approach to encoding, based on one of the below encoding modes:

DefaultUriBuilderFactory实现在内部使用UriComponentsBuilder来扩展和编码 URI 模板。作为一个工厂类，它提供了一个单一的地方来配置编码方法，基于以下编码模式之一：

• TEMPLATE_AND_VALUES: Uses UriComponentsBuilder#encode(), corresponding to the first option in the earlier list, to pre-encode the URI template and strictly encode URI variables when expanded.

• TEMPLATE_AND_VALUES：使用UriComponentsBuilder#encode()（对应于前面列表中的第一个选项）对 URI 模板进行预编码，并在扩展时对 URI 变量进行严格编码。

• VALUES_ONLY: Does not encode the URI template and, instead, applies strict encoding to URI variables through UriUtils#encodeUriVariables prior to expanding them into the template.

• VALUES_ONLY: 不对 URI 模板进行编码，而是在将 URI 变量扩展到模板之前通过UriUtils#encodeUriVariables 对URI 变量进行严格编码。

• URI_COMPONENT: Uses UriComponents#encode(), corresponding to the second option in the earlier list, to encode URI component value after URI variables are expanded.

• URI_COMPONENT：使用UriComponents#encode()(对应于前面列表中的第二个选项)在URI 变量扩展后对 URI 组件值进行编码。

• NONE: No encoding is applied.

• NONE: 没有应用编码。

The RestTemplate is set to EncodingMode.URI_COMPONENT for historic reasons and for backwards compatibility. The WebClient relies on the default value in DefaultUriBuilderFactory, which was changed from EncodingMode.URI_COMPONENT in 5.0.x to EncodingMode.TEMPLATE_AND_VALUES in 5.1.

RestTemplate设置为EncodingMode.URI_COMPONENT是由于历史原因和向后兼容性。WebClient依赖于DefaultUriBuilderFactory中的缺省值(其由5.0.x的EncodingMode.URI_COMPONENT变为5.1的EncodingMode.TEMPLATE_AND_VALUES)。

1.7. CORS 【跨域？】

Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so.

Spring WebFlux 可让您处理 CORS（跨源资源共享）。本节介绍如何执行此操作。

1.7.1. Introduction 【介绍】

For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts from evil.com should not be able to make AJAX requests to your bank API with your credentials — for example, withdrawing money from your account!

出于安全原因，浏览器禁止对当前源之外的资源进行 AJAX 调用。例如，您可以在一个选项卡中拥有您的银行帐户，而在另一个选项卡中拥有 evil.com。来自 evil.com 的脚本不应能够使用您的凭据向您的银行 API 发出 AJAX 请求——例如，从您的帐户中取款！

Cross-Origin Resource Sharing (CORS) is a W3C specification implemented by most browsers that lets you specify what kind of cross-domain requests are authorized, rather than using less secure and less powerful workarounds based on IFRAME or JSONP.

跨源资源共享 (CORS) 是被大多数浏览器 实现的W3C 规范，它允许您指定何种跨域请求类型被授权/允许，而不是使用基于 IFRAME 或 JSONP 的安全性较低且功能较弱的解决方法。

1.7.2. Processing

The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read this article, among many others, or see the specification for more details.

CORS 规范区分了预检请求、简单请求和实际请求。要了解 CORS 的工作原理，您可以阅读 本文，或查看规范以获取更多详细信息。

Spring WebFlux HandlerMapping implementations provide built-in support for CORS. After successfully mapping a request to a handler, a HandlerMapping checks the CORS configuration for the given request and handler and takes further actions. Preflight requests are handled directly, while simple and actual CORS requests are intercepted, validated, and have the required CORS response headers set.

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

In order to enable cross-origin requests (that is, the Origin header is present and differs from the host of the request), you need to have some explicitly declared CORS configuration. If no matching CORS configuration is found, preflight requests are rejected. No CORS headers are added to the responses of simple and actual CORS requests and, consequently, browsers reject them.

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

Each HandlerMapping can be configured individually with URL pattern-based CorsConfiguration mappings. In most cases, applications use the WebFlux Java configuration to declare such mappings, which results in a single, global map passed to all HandlerMapping implementations.

每个HandlerMapping都可以使用基于 URL 模式的CorsConfiguration映射单独配置。在大多数情况下，应用程序使用 WebFlux Java 配置来声明此类映射，这会使得一个单个的全局map传递给所有的HandlerMapping实现。

You can combine global CORS configuration at the HandlerMapping level with more fine-grained, handler-level CORS configuration. For example, annotated controllers can use class- or method-level @CrossOrigin annotations (other handlers can implement CorsConfigurationSource).

您可以将HandlerMapping级别的全局 CORS 配置与更细粒度的处理程序级别的 CORS 配置相结合。例如，带注解的控制器可以使用类或方法级别的@CrossOrigin注解（其他处理程序可以实现CorsConfigurationSource）。

The rules for combining global and local configuration are generally additive — for example, all global and all local origins. For those attributes where only a single value can be accepted, such as allowCredentials and maxAge, the local overrides the global value. See CorsConfiguration#combine(CorsConfiguration) for more details.

组合全局和本地配置的规则通常是叠加的——例如，所有全局和所有本地来源。对于那些只能接受单个值的属性，例如allowCredentials和maxAge，本地值会覆盖全局值。获取更多详细信息，请参阅 CorsConfiguration#combine(CorsConfiguration) 。

To learn more from the source or to make advanced customizations, see:

要从源中了解更多信息或进行高级自定义，请参阅：

• CorsConfiguration
• CorsProcessor and DefaultCorsProcessor
• AbstractHandlerMapping

1.7.3. @CrossOrigin

The @CrossOrigin annotation enables cross-origin requests on annotated controller methods, as the following example shows:

@CrossOrigin 注解使得带注解的控制器方法能够跨域请求，如下面的示例所示：

@RestController
@RequestMapping("/account")
public class AccountController {

    @CrossOrigin
    @GetMapping("/{id}")
    public Mono<Account> retrieve(@PathVariable Long id) {
        // ...
    }

    @DeleteMapping("/{id}")
    public Mono<Void> remove(@PathVariable Long id) {
        // ...
    }
}

By default, @CrossOrigin allows:

默认情况下，@CrossOrigin允许：

• All origins. 一切源。

• All headers. 所有头信息。

• All HTTP methods to which the controller method is mapped.
  所有控制器方法所映射的 HTTP 方法。

allowCredentials is not enabled by default, since that establishes a trust level that exposes sensitive user-specific information (such as cookies and CSRF tokens) and should be used only where appropriate. When it is enabled either allowOrigins must be set to one or more specific domain (but not the special value "*") or alternatively the allowOriginPatterns property may be used to match to a dynamic set of origins.

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

maxAge is set to 30 minutes.

maxAge 设置为 30 分钟。

@CrossOrigin is supported at the class level, too, and inherited by all methods. The following example specifies a certain domain and sets maxAge to an hour:

@CrossOrigin在类级别也受支持，并由所有方法继承。以下示例指定某个域并设置maxAge为小时：

@CrossOrigin(origins = "https://domain2.com", maxAge = 3600)
@RestController
@RequestMapping("/account")
public class AccountController {

    @GetMapping("/{id}")
    public Mono<Account> retrieve(@PathVariable Long id) {
        // ...
    }

    @DeleteMapping("/{id}")
    public Mono<Void> remove(@PathVariable Long id) {
        // ...
    }
}

You can use @CrossOrigin at both the class and the method level, as the following example shows:

您可以在类和方法级别同时使用@CrossOrigin，如以下示例所示：

@CrossOrigin(maxAge = 3600) //(1)
@RestController
@RequestMapping("/account")
public class AccountController {

    @CrossOrigin("https://domain2.com") //(2)
    @GetMapping("/{id}")
    public Mono<Account> retrieve(@PathVariable Long id) {
        
    }

    @DeleteMapping("/{id}")
    public Mono<Void> remove(@PathVariable Long id) {
        
    }
}

(1) Using @CrossOrigin at the class level.
(2) Using @CrossOrigin at the method level.

1.7.4. Global Configuration 【全局配置】

In addition to fine-grained, controller method-level configuration, you probably want to define some global CORS configuration, too. You can set URL-based CorsConfiguration mappings individually on any HandlerMapping. Most applications, however, use the WebFlux Java configuration to do that.

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

By default global configuration enables the following:

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

• All origins.

• All headers.

• GET, HEAD, and POST methods.

allowedCredentials is not enabled by default, since that establishes a trust level that exposes sensitive user-specific information(such as cookies and CSRF tokens) and should be used only where appropriate. When it is enabled either allowOrigins must be set to one or more specific domain (but not the special value "*") or alternatively the allowOriginPatterns property may be used to match to a dynamic set of origins.

allowedCredentials默认情况下不启用，因为这建立了能暴露特定于用户的应仅在适当的情况下才使用的敏感信息（例如 cookie 和 CSRF 令牌）的信任级别。启用时，allowOrigins必须被设置为一个或多个特定域（但不能是特殊值"*"），或者该allowOriginPatterns属性可用于匹配一组动态来源。

maxAge is set to 30 minutes.

maxAge 设置为 30 分钟。

To enable CORS in the WebFlux Java configuration, you can use the CorsRegistry callback, as the following example shows:

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

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {

        registry.addMapping("/api/**")
            .allowedOrigins("https://domain2.com")
            .allowedMethods("PUT", "DELETE")
            .allowedHeaders("header1", "header2", "header3")
            .exposedHeaders("header1", "header2")
            .allowCredentials(true).maxAge(3600);

        // Add more mappings...
    }
}

1.7.5. CORS WebFilter

Web MVC

You can apply CORS support through the built-in CorsWebFilter, which is a good fit with functional endpoints.

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

If you try to use the CorsFilter with Spring Security, keep in mind that Spring Security has built-in support for CORS.

如果您尝试使用CorsFilter搭配Spring Security，请记住，Spring Security内置地为CORS提供了支持。

To configure the filter, you can declare a CorsWebFilter bean and pass a CorsConfigurationSource to its constructor, as the following example shows:

要配置过滤器，您可以声明一个CorsWebFilterbean 并将一个CorsConfigurationSource传递给其构造函数，如以下示例所示：

@Bean
CorsWebFilter corsFilter() {

    CorsConfiguration config = new CorsConfiguration();

    // Possibly...
    // config.applyPermitDefaultValues()

    config.setAllowCredentials(true);
    config.addAllowedOrigin("https://domain1.com");
    config.addAllowedHeader("*");
    config.addAllowedMethod("*");

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", config);

    return new CorsWebFilter(source);
}

1.8. Web Security 【 网络安全】

The Spring Security project provides support for protecting web applications from malicious exploits. See the Spring Security reference documentation, including:

Spring Security的项目提供了保护Web应用程序免受恶意攻击的支持。请参阅 Spring Security 参考文档，包括：

• WebFlux Security

• WebFlux Testing Support

• CSRF Protection

• Security Response Headers

1.9. View Technologies 【视图技术】

The use of view technologies in Spring WebFlux is pluggable. Whether you decide to use Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a configuration change. This chapter covers the view technologies integrated with Spring WebFlux. We assume you are already familiar with View Resolution.

Spring WebFlux 中视图技术的使用是可插拔的。无论您决定使用 Thymeleaf、FreeMarker 还是其他一些视图技术，主要就是更改配置的问题。本章涵盖了与 Spring WebFlux 集成的视图技术。我们假设您已经熟悉View Resolution。

1.9.1. Thymeleaf 【百里香模板引擎】

Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful for independent work on UI templates (for example, by a designer) without the need for a running server. Thymeleaf offers an extensive set of features, and it is actively developed and maintained. For a more complete introduction, see the Thymeleaf project home page.

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

The Thymeleaf integration with Spring WebFlux is managed by the Thymeleaf project. The configuration involves a few bean declarations, such as SpringResourceTemplateResolver, SpringWebFluxTemplateEngine, and ThymeleafReactiveViewResolver. For more details, see Thymeleaf+Spring and the WebFlux integration announcement.

Thymeleaf 与 Spring WebFlux 的集成由 Thymeleaf 项目管理。配置涉及几个bean声明，如 SpringResourceTemplateResolver，SpringWebFluxTemplateEngine和 ThymeleafReactiveViewResolver。有关更多详细信息，请参阅 Thymeleaf+Spring和 WebFlux 集成 公告。

1.9.2. FreeMarker 【自由标记】

Apache FreeMarker is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in integration for using Spring WebFlux with FreeMarker templates.

Apache FreeMarker是一个模板引擎，用于从 HTML 到电子邮件等生成任何类型的文本输出。Spring 框架内置了将 Spring WebFlux 与 FreeMarker 模板结合使用的集成。

View Configuration 【视图配置】

The following example shows how to configure FreeMarker as a view technology:

以下示例展示了如何将 FreeMarker 配置为视图技术：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.freeMarker();
    }

    // Configure FreeMarker...

    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() {
        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        configurer.setTemplateLoaderPath("classpath:/templates/freemarker");
        return configurer;
    }
}

Your templates need to be stored in the directory specified by the FreeMarkerConfigurer, shown in the preceding example. Given the preceding configuration, if your controller returns the view name, welcome, the resolver looks for the classpath:/templates/freemarker/welcome.ftl template.

您的模板需要存储在被FreeMarkerConfigurer指定的目录中，如前面的示例所示。鉴于前面的配置，如果您的控制器返回视图名称，welcome，解析器会查找 classpath:/templates/freemarker/welcome.ftl模板。

FreeMarker Configuration 【自由标记 配置】

You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker Configuration object (which is managed by Spring) by setting the appropriate bean properties on the FreeMarkerConfigurer bean. The freemarkerSettings property requires a java.util.Properties object, and the freemarkerVariables property requires a java.util.Map. The following example shows how to use a FreeMarkerConfigurer:

您可以通过在FreeMarkerConfigurer bean 上设置适当的 bean 属性，从而将 FreeMarker 的 'Settings' 和 'SharedVariables' 直接传递给 FreeMarker Configuration对象（由 Spring 管理）。freemarkerSettings属性需要一个java.util.Properties对象，freemarkerVariables属性需要一个 java.util.Map。 以下示例显示了如何使用FreeMarkerConfigurer：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    // ...
    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() {
        Map<String, Object> variables = new HashMap<>();
        variables.put("xml_escape", new XmlEscape());

        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        configurer.setTemplateLoaderPath("classpath:/templates");
        configurer.setFreemarkerVariables(variables);
        return configurer;
    }
}

See the FreeMarker documentation for details of settings and variables as they apply to the Configuration object.

有关应用于Configuration对象的设置和变量的详细信息，请参阅 FreeMarker 文档。

Form Handling 【表单处理】

Spring provides a tag library for use in JSPs that contains, among others, a <spring:bind/> element. This element primarily lets forms display values from form-backing objects and show the results of failed validations from a Validator in the web or business tier. Spring also has support for the same functionality in FreeMarker, with additional convenience macros for generating form input elements themselves.

Spring 提供了一个在 JSP 中使用的标记库，其中包含一个 <spring:bind/>元素。此元素主要让表单显示来自表单支持对象的值，并显示来自Web 或业务层的Validator的验证失败的结果。Spring 还支持 FreeMarker 中的相同功能，以及用于生成表单输入元素本身的额外便利宏。

The Bind Macros 【绑定宏】

A standard set of macros are maintained within the spring-webflux.jar file for FreeMarker, so they are always available to a suitably configured application.

spring-webflux.jar文件中为FreeMarker维护了一组标准的宏，因此它们始终可供适当配置的应用程序使用。

Some of the macros defined in the Spring templating libraries are considered internal (private), but no such scoping exists in the macro definitions, making all macros visible to calling code and user templates. The following sections concentrate only on the macros you need to directly call from within your templates. If you wish to view the macro code directly, the file is called spring.ftl and is in the org.springframework.web.reactive.result.view.freemarker package.

Spring 模板库中定义的一些宏被认为是内部的（私有的），但宏定义中不存在这样的范围限制，使得所有宏对调用代码和用户模板是可见的。以下部分仅关注您需要从模板中直接调用的宏。如果您希望直接查看宏代码，则在spring.ftl文件的org.springframework.web.reactive.result.view.freemarker包中。

For additional details on binding support, see Simple Binding for Spring MVC.

有关绑定支持的其他详细信息，请参阅Spring MVC 的简单绑定。

Form Macros 【表单宏】

For details on Spring’s form macro support for FreeMarker templates, consult the following sections of the Spring MVC documentation.

有关 Spring 对 FreeMarker 模板的表单宏支持的详细信息，请参阅 Spring MVC 文档的以下部分。

• Input Macros
• Input Fields
• Selection Fields
• HTML Escaping

1.9.3. Script Views 【脚本视图】

The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the JSR-223 Java scripting engine. The following table shows the templating libraries that we have tested on different script engines:

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

Scripting Library	Scripting Engine
Handlebars	Nashorn
Mustache	Nashorn
React	Nashorn
EJS	Nashorn
ERB	JRuby
String templates	Jython
Kotlin Script templating	Kotlin

The basic rule for integrating any other script engine is that it must implement the ScriptEngine and Invocable interfaces.

集成任何其他脚本引擎的基本规则是，它必须实现ScriptEngine和Invocable接口。

Requirements 【依赖】

You need to have the script engine on your classpath, the details of which vary by script engine:

您需要在classpath上安装脚本引擎，其详细信息因脚本引擎而异：

• The Nashorn JavaScript engine is provided with Java 8+. Using the latest update release available is highly recommended.

• 犀牛的JavaScript引擎在Java 8+版本提供。强烈建议使用可用的最新更新版本。

• JRuby should be added as a dependency for Ruby support.

• JRuby应该作为 Ruby 支持的依赖项添加。

• Jython should be added as a dependency for Python support.

• Jython应该作为 Python 支持的依赖项添加。

• org.jetbrains.kotlin:kotlin-script-util dependency and a META-INF/services/javax.script.ScriptEngineFactory file containing a org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory line should be added for Kotlin script support. See this example for more detail.

• org.jetbrains.kotlin:kotlin-script-util依赖项和包含org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory行的META-INF/services/javax.script.ScriptEngineFactory 文件应作为 Kotlin 脚本的支持添加。有关更多详细信息，请参阅 此示例。

You need to have the script templating library. One way to do that for JavaScript is through WebJars.

您需要有脚本模板库。对 JavaScript 执行此操作的一种方法是通过WebJars。

Script Templates 【脚本模板】

You can declare a ScriptTemplateConfigurer bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. The following example uses Mustache templates and the Nashorn JavaScript engine:

您可以声明一个ScriptTemplateConfigurerbean 来指定要使用的脚本引擎、要加载的脚本文件、要调用哪些函数来渲染模板等。以下示例使用 Mustache 模板和 Nashorn JavaScript 引擎：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.scriptTemplate();
    }

    @Bean
    public ScriptTemplateConfigurer configurer() {
        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();
        configurer.setEngineName("nashorn");
        configurer.setScripts("mustache.js");
        configurer.setRenderObject("Mustache");
        configurer.setRenderFunction("render");
        return configurer;
    }
}

The render function is called with the following parameters:

使用以下参数调用render函数：

• String template: The template content 模板内容

• Map model: The view model 视图模型

• RenderingContext renderingContext: The RenderingContext that gives access to the application context, the locale, the template loader, and the URL (since 5.0)

• RenderingContext renderingContext: RenderingContext允许访问应用程序上下文、语言环境、模板加载器和 URL（自 5.0 起）

Mustache.render() is natively compatible with this signature, so you can call it directly.

此签名的Mustache.render() 是本地兼容的，因此您可以直接调用它。

If your templating technology requires some customization, you can provide a script that implements a custom render function. For example, Handlerbars needs to compile templates before using them and requires a polyfill in order to emulate some browser facilities not available in the server-side script engine. The following example shows how to set a custom render function:

如果您的模板技术需要一些自定义，您可以提供一个实现自定义渲染功能的脚本。例如，Handlerbars 需要在使用模板之前编译它们，并且需要一个 polyfill来模拟一些在服务器端脚本引擎中不可用的浏览器设施。以下示例显示了如何设置自定义渲染功能：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.scriptTemplate();
    }

    @Bean
    public ScriptTemplateConfigurer configurer() {
        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();
        configurer.setEngineName("nashorn");
        configurer.setScripts("polyfill.js", "handlebars.js", "render.js");
        configurer.setRenderFunction("render");
        configurer.setSharedEngine(false);
        return configurer;
    }

Setting the sharedEngine property to false is required when using non-thread-safe script engines with templating libraries not designed for concurrency, such as Handlebars or React running on Nashorn. In that case, Java SE 8 update 60 is required, due to this bug, but it is generally recommended to use a recent Java SE patch release in any case.

当将非线程安全脚本引擎和非为并发设计的模板库一起使用时（例如在 Nashorn 上运行 Handlebars 或 React）需要将sharedEngine属性设置为false。在这种情况下，由于此错误，你需要 Java SE 8 60以上的版本 ，但通常建议在任何情况下都使用最新的 Java SE 补丁版本。

polyfill.js defines only the window object needed by Handlebars to run properly, as the following snippet shows:

polyfill.js定义中仅window对象是Handlebars 正常运行所需，如以下代码段所示：

var window = {};

This basic render.js implementation compiles the template before using it. A production ready implementation should also store and reused cached templates or pre-compiled templates. This can be done on the script side, as well as any customization you need (managing template engine configuration for example). The following example shows how compile a template:

这个基本render.js实现在模板被使用之前编译它。生产就绪实现还应存储和重用缓存模板或预编译模板。这可以在脚本端完成，也可以在您需要的任何自定义（例如管理模板引擎配置）上完成。以下示例显示了如何编译模板：

function render(template, model) {
    var compiledTemplate = Handlebars.compile(template);
    return compiledTemplate(model);
}

Check out the Spring Framework unit tests, Java, and resources, for more configuration examples.

查看 Spring Framework 单元测试、 Java和 资源，以获取更多配置示例。

1.9.4. JSON and XML

For Content Negotiation purposes, it is useful to be able to alternate between rendering a model with an HTML template or as other formats (such as JSON or XML), depending on the content type requested by the client. To support doing so, Spring WebFlux provides the HttpMessageWriterView, which you can use to plug in any of the available Codecs from spring-web, such as Jackson2JsonEncoder, Jackson2SmileEncoder, or Jaxb2XmlEncoder.

出于内容协商的目的，根据客户端请求的内容类型，能够交替使用 HTML 模板或其他格式（例如 JSON 或 XML）进行渲染模型非常有用。为了支持这样做，Spring WebFlux提供了HttpMessageWriterView，您可以将它用于任何spring-web支持的编解码器中，比如Jackson2JsonEncoder，Jackson2SmileEncoder或者Jaxb2XmlEncoder。

Unlike other view technologies, HttpMessageWriterView does not require a ViewResolver but is instead configured as a default view. You can configure one or more such default views, wrapping different HttpMessageWriter instances or Encoder instances. The one that matches the requested content type is used at runtime.

与其他视图技术不同，HttpMessageWriterView不需要一个ViewResolver 而是配置为默认视图。您可以配置一个或多个这样的默认视图，包装不同的HttpMessageWriter实例或Encoder实例。在运行时使用其中一个与请求内容类型匹配的。

In most cases, a model contains multiple attributes. To determine which one to serialize, you can configure HttpMessageWriterView with the name of the model attribute to use for rendering. If the model contains only one attribute, that one is used.

大多数情况下，一个模型包含多个属性。要决定序列化哪一个，您可以使用将用于渲染的模型属性的名称来配置HttpMessageWriterView。如果模型仅包含一个属性，则使用该属性。

1.10. HTTP Caching 【HTTP缓存】

HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the Cache-Control response header and subsequent conditional request headers, such as Last-Modified and ETag. Cache-Control advises private (for example, browser) and public (for example, proxy) caches how to cache and re-use responses. An ETag header is used to make a conditional request that may result in a 304 (NOT_MODIFIED) without a body, if the content has not changed. ETag can be seen as a more sophisticated successor to the Last-Modified header.

HTTP 缓存可以显著提高 Web 应用程序的性能。HTTP 缓存围绕Cache-Control响应头和后续条件请求头，例如Last-Modified和ETag。Cache-Control用于建议私有（例如，浏览器）缓存和公共（例如，代理）缓存如何缓存和重用响应。如果内容没有改变，ETag头用于发出没有正文的可能导致304（NOT_MODIFIED）的条件请求。ETag可以看作是Last-Modified头的更复杂的继承者。

This section describes the HTTP caching related options available in Spring WebFlux.

本节介绍 Spring WebFlux 中可用的 HTTP 缓存相关选项。

1.10.1. CacheControl

CacheControl provides support for configuring settings related to the Cache-Control header and is accepted as an argument in a number of places:

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

While RFC 7234 describes all possible directives for the Cache-Control response header, the CacheControl type takes a use case-oriented approach that focuses on the common scenarios, as the following example shows:

虽然RFC 7234描述了Cache-Control响应头的所有可能指令，但该CacheControl类型采用面向用例的方法，专注于常见场景，如以下示例所示：

// Cache for an hour - "Cache-Control: max-age=3600"
CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS);

// Prevent caching - "Cache-Control: no-store"
CacheControl ccNoStore = CacheControl.noStore();

// Cache for ten days in public and private caches,
// public caches should not transform the response
// "Cache-Control: max-age=864000, public, no-transform"
CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic();

1.10.2. Controllers 【控制器】

Controllers can add explicit support for HTTP caching. We recommend doing so, since the lastModified or ETag value for a resource needs to be calculated before it can be compared against conditional request headers. A controller can add an ETag and Cache-Control settings to a ResponseEntity, as the following example shows:

控制器可以添加对 HTTP 缓存的显式支持。我们建议这样做，因为需要先计算资源的 lastModifiedorETag值，然后才能将其与条件请求头进行比较。控制器可以将ETag和Cache-Control 设置添加到ResponseEntity，如以下示例所示：

@GetMapping("/book/{id}")
public ResponseEntity<Book> showBook(@PathVariable Long id) {

    Book book = findBook(id);
    String version = book.getVersion();

    return ResponseEntity
            .ok()
            .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS))
            .eTag(version)  // lastModified is also available
            .body(book);
}

The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison to the conditional request headers indicates the content has not changed. Otherwise, the ETag and Cache-Control headers are added to the response.

如果与条件请求头的比较表明内容未更改，则前面的示例发送空正文的 304 (NOT_MODIFIED) 响应。否则，将 ETag和Cache-Control头添加到响应中。

You can also make the check against conditional request headers in the controller, as the following example shows:

您还可以对控制器中的条件请求头进行检查，如以下示例所示：

@RequestMapping
public String myHandleMethod(ServerWebExchange exchange, Model model) {

    long eTag = ... //(1)

    if (exchange.checkNotModified(eTag)) {
        return null; //(2)
    }

    model.addAttribute(...); //(3)
    return "myViewName";
}

(1) Application-specific calculation.
(2) Response has been set to 304 (NOT_MODIFIED). No further processing.
(3) Continue with request processing.

(1) 特定于应用程序的计算。
(2) 响应已设置为 304 (NOT_MODIFIED)。没有进一步处理。
(3) 继续请求处理。

There are three variants for checking conditional requests against eTag values, lastModified values, or both. For conditional GET and HEAD requests, you can set the response to 304 (NOT_MODIFIED). For conditional POST, PUT, and DELETE, you can instead set the response to 412 (PRECONDITION_FAILED) to prevent concurrent modification.

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

1.10.3. Static Resources 【静态资源】

You should serve static resources with a Cache-Control and conditional response headers for optimal performance. See the section on configuring Static Resources.

您应该使用Cache-Control和条件响应头为静态资源提供最佳性能。请参阅配置静态资源部分。

1.11. WebFlux Config 【WebFlux 配置】

The WebFlux Java configuration declares the components that are required to process requests with annotated controllers or functional endpoints, and it offers an API to customize the configuration. That means you do not need to understand the underlying beans created by the Java configuration. However, if you want to understand them, you can see them in WebFluxConfigurationSupport or read more about what they are in Special Bean Types.

WebFlux Java 配置声明了处理请求所需的的注解控制器或函数式端点组件，并提供了一个 API 来自定义配置。这意味着您不需要了解由 Java 配置创建的底层 bean。但是，如果您想了解它们，可以在WebFluxConfigurationSupport或Special Bean Types查看它们。

For more advanced customizations, not available in the configuration API, you can gain full control over the configuration through the Advanced Configuration Mode.

对于配置 API 中不可用的更高级自定义，您可以通过高级配置模式获得对配置的完全控制 。

1.11.1. Enabling WebFlux Config 【启用 WebFlux 配置】

You can use the @EnableWebFlux annotation in your Java config, as the following example shows:

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

@Configuration
@EnableWebFlux
public class WebConfig {
}

The preceding example registers a number of Spring WebFlux infrastructure beans and adapts to dependencies available on the classpath — for JSON, XML, and others.

前面的示例注册了许多 Spring WebFlux 基础设施 bean并适配classpath上可用的依赖项——对于 JSON、XML 和其他。

1.11.2. WebFlux config API 【WebFlux 配置 API】

In your Java configuration, you can implement the WebFluxConfigurer interface, as the following example shows:

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

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    // Implement configuration methods...
}

1.11.3. Conversion, formatting 【转换、格式化】

By default, formatters for various number and date types are installed, along with support for customization via @NumberFormat and @DateTimeFormat on fields.

默认情况下，已安装了各种数字和日期类型的格式化程序，并支持通过@NumberFormat和@DateTimeFormat字段进行自定义。

To register custom formatters and converters in Java config, use the following:

要在 Java 配置中注册自定义格式化程序和转换器，请使用以下命令：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        // ...
    }
}

By default Spring WebFlux considers the request Locale when parsing and formatting date values. This works for forms where dates are represented as Strings with "input" form fields. For "date" and "time" form fields, however, browsers use a fixed format defined in the HTML spec. For such cases date and time formatting can be customized as follows:

默认情况下，Spring WebFlux 在解析或格式化日期值时会考虑请求的区域设置。这适用于将“input”表单字段日期表示为字符串的表单。但是，对于“日期”和“时间”表单字段，浏览器使用 HTML 规范中定义的固定格式。对于这种情况，可以按如下方式自定义日期和时间格式：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
        registrar.setUseIsoFormat(true);
        registrar.registerFormatters(registry);
    }
}

See FormatterRegistrar SPI and the FormattingConversionServiceFactoryBean for more information on when to use FormatterRegistrar implementations.

有关何时使用FormatterRegistrar实现类的更多信息，请参阅 FormatterRegistrar SPI 和FormattingConversionServiceFactoryBean。

1.11.4. Validation 【验证】

By default, if Bean Validation is present on the classpath (for example, the Hibernate Validator), the LocalValidatorFactoryBean is registered as a global validator for use with @Valid and @Validated on @Controller method arguments.

默认情况下，如果Bean验证存在于classpath（例如，Hibernate验证）时，LocalValidatorFactoryBean 被注册为全球验证器，用作@Valid和 @Validated上@Controller注解方法的参数。

In your Java configuration, you can customize the global Validator instance, as the following example shows:

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

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public Validator getValidator(); {
        // ...
    }
}

Note that you can also register Validator implementations locally, as the following example shows:

请注意，您还可以局部注册Validator的实现类，如以下示例所示：

@Controller
public class MyController {
    @InitBinder
    protected void initBinder(WebDataBinder binder) {
        binder.addValidators(new FooValidator());
    }
}

If you need to have a LocalValidatorFactoryBean injected somewhere, create a bean and mark it with @Primary in order to avoid conflict with the one declared in the MVC config.

如果您需要在某处注入一个LocalValidatorFactoryBean bean，请创建一个 bean 并将其标记@Primary以避免与 MVC 配置中声明的 bean冲突。

1.11.5. Content Type Resolvers 【内容类型解析器】

You can configure how Spring WebFlux determines the requested media types for @Controller instances from the request. By default, only the Accept header is checked, but you can also enable a query parameter-based strategy.

您可以配置 Spring WebFlux 如何根据请求为@Controller实例确定此次来的请求的媒体类型 。默认情况下，只检查Accept头信息，但您也可以启用基于查询参数的策略。

The following example shows how to customize the requested content type resolution:

以下示例显示如何自定义请求的内容类型解析：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
        // ...
    }
}

1.11.6. HTTP message codecs 【HTTP 消息编解码器】

The following example shows how to customize how the request and response body are read and written:

以下示例显示如何自定义读取和写入请求和响应正文的方式：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
        configurer.defaultCodecs().maxInMemorySize(512 * 1024);
    }
}

ServerCodecConfigurer provides a set of default readers and writers. You can use it to add more readers and writers, customize the default ones, or replace the default ones completely.

ServerCodecConfigurer提供一组默认的读取器和写入器。您可以使用它来添加更多的读取器和写入器，自定义默认的，或完全替换默认的。

For Jackson JSON and XML, consider using Jackson2ObjectMapperBuilder, which customizes Jackson’s default properties with the following ones:

对于 Jackson JSON 和 XML，请考虑使用Jackson2ObjectMapperBuilder，它使用下列内容自定义 Jackson 的默认属性：

• DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES is disabled.

• MapperFeature.DEFAULT_VIEW_INCLUSION is disabled.

It also automatically registers the following well-known modules if they are detected on the classpath:

如果在classpath中检测到以下众所周知的模块，还会自动注册它们：

• jackson-datatype-joda: Support for Joda-Time types.

• jackson-datatype-jsr310: Support for Java 8 Date and Time API types.

• jackson-datatype-jdk8: Support for other Java 8 types, such as Optional.

• jackson-module-kotlin: Support for Kotlin classes and data classes.

1.11.7. View Resolvers 【视图解析器】

The following example shows how to configure view resolution:

以下示例显示了如何配置视图解析器：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        // ...
    }
}

The ViewResolverRegistry has shortcuts for view technologies with which the Spring Framework integrates. The following example uses FreeMarker (which also requires configuring the underlying FreeMarker view technology):

ViewResolverRegistry有快捷方式用于与Spring框架集成的视图技术。以下示例使用 FreeMarker（也需要配置底层的 FreeMarker 视图技术）：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.freeMarker();
    }
    
    // Configure Freemarker...
    
    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() {
        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        configurer.setTemplateLoaderPath("classpath:/templates");
        return configurer;
    }
}

You can also plug in any ViewResolver implementation, as the following example shows:

您还可以引入任何ViewResolver实现，如以下示例所示：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        ViewResolver resolver = ... ;
        registry.viewResolver(resolver);
    }
}

To support Content Negotiation and rendering other formats through view resolution (besides HTML), you can configure one or more default views based on the HttpMessageWriterView implementation, which accepts any of the available Codecs from spring-web. The following example shows how to do so:

为了支持内容协商，并通过视图解析器（除HTML）渲染其他格式，可以根据配置一个或多个默认视图（基于HttpMessageWriterView的实现），它接受任何spring-web中可用的 编解码器。以下示例显示了如何执行此操作：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.freeMarker();

        Jackson2JsonEncoder encoder = new Jackson2JsonEncoder();
        registry.defaultViews(new HttpMessageWriterView(encoder));
    }

    // ...
}

See View Technologies for more on the view technologies that are integrated with Spring WebFlux.

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

1.11.8. Static Resources 【静态资源】

This option provides a convenient way to serve static resources from a list of Resource-based locations.

此选项提供了一种从基于Resource位置的列表提供静态资源的便捷方法 。

In the next example, given a request that starts with /resources, the relative path is used to find and serve static resources relative to /static on the classpath. Resources are served with a one-year future expiration to ensure maximum use of the browser cache and a reduction in HTTP requests made by the browser. The Last-Modified header is also evaluated and, if present, a 304 status code is returned. The following list shows the example:

在下例中，给定以/resources开头的请求，相对路径用于查找和提供相对于 classpath: /static路径的静态资源。资源在未来一年内到期，以确保最大限度地使用浏览器缓存并减少浏览器发出的 HTTP 请求。还会计算Last-Modified头，如果存在，返回一个304状态码。以下列表显示了示例：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/resources/**")
                .addResourceLocations("/public", "classpath:/static/")
                .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS));
    }
}

The resource handler also supports a chain of ResourceResolver implementations and ResourceTransformer implementations, which can be used to create a toolchain for working with optimized resources.

资源处理程序还支持ResourceResolver实现类和 ResourceTransformer实现类的链 —— 可用于创建用于处理优化资源的工具链。

You can use the VersionResourceResolver for versioned resource URLs based on an MD5 hash computed from the content, a fixed application version, or other information. A ContentVersionStrategy (MD5 hash) is a good choice with some notable exceptions (such as JavaScript resources used with a module loader).

您可以使用VersionResourceResolver基于（由内容、固定应用程序版本号或其他信息计算来的 ）MD5 哈希来版本化资源 URL。 ContentVersionStrategy(MD5 hash) 是一个不错的选择，但有一些值得注意的例外（例如与模块加载器一起使用的 JavaScript 资源）。

The following example shows how to use VersionResourceResolver in your Java configuration:

以下示例显示了如何VersionResourceResolver在 Java 配置中使用：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/resources/**")
                .addResourceLocations("/public/")
                .resourceChain(true)
                .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));
    }

}

You can use ResourceUrlProvider to rewrite URLs and apply the full chain of resolvers and transformers (for example, to insert versions). The WebFlux configuration provides a ResourceUrlProvider so that it can be injected into others.

您可以使用ResourceUrlProvider来重写 URL 并应用完整的解析器和转换器链（例如，插入版本）。WebFlux 配置提供了ResourceUrlProvider 以便它可以被注入到其他里面。

Unlike Spring MVC, at present, in WebFlux, there is no way to transparently rewrite static resource URLs, since there are no view technologies that can make use of a non-blocking chain of resolvers and transformers. When serving only local resources, the workaround is to use ResourceUrlProvider directly (for example, through a custom element) and block.

与 Spring MVC 不同，目前在 WebFlux 中，没有办法透明地重写静态资源 URL，因为没有视图技术可以利用解析器和转换器的非阻塞链。当仅提供本地资源时，解决方法是直接使用ResourceUrlProvider （例如，通过自定义元素）并阻塞。

Note that, when using both EncodedResourceResolver (for example, Gzip, Brotli encoded) and VersionedResourceResolver, they must be registered in that order, to ensure content-based versions are always computed reliably based on the unencoded file.

请注意，当同时使用EncodedResourceResolver（例如，Gzip、Brotli 编码）和 VersionedResourceResolver 时，它们必须按该顺序注册，以确保始终基于未编码的文件可靠地计算基于内容的版本信息。

WebJars are also supported through the WebJarsResourceResolver which is automatically registered when the org.webjars:webjars-locator-core library is present on the classpath. The resolver can re-write URLs to include the version of the jar and can also match against incoming URLs without versions — for example, from /jquery/jquery.min.js to /jquery/1.2.0/jquery.min.js.

WebJars通过WebJarsResourceResolver（当org.webjars:webjars-locator-core库存在于 classpath 中时，会自动注册）受到支持。来自动注册。解析器可以重写 URL 以包含 jar 的版本，也可以匹配没有版本信息的传入 URL——例如， from /jquery/jquery.min.jsto /jquery/1.2.0/jquery.min.js。

The Java configuration based on ResourceHandlerRegistry provides further options for fine-grained control, e.g. last-modified behavior and optimized resource resolution.

基于的 Java 配置ResourceHandlerRegistry为细粒度控制提供了更多选项，例如最后修改的行为和优化的资源分辨率。

1.11.9. Path Matching 【路径匹配】

You can customize options related to path matching. For details on the individual options, see the PathMatchConfigurer javadoc. The following example shows how to use PathMatchConfigurer:

您可以自定义与路径匹配相关的选项。有关各个选项的详细信息，请参阅 PathMatchConfigurerjavadoc。以下示例显示了如何使用PathMatchConfigurer：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer
            .setUseCaseSensitiveMatch(true)
            .setUseTrailingSlashMatch(false)
            .addPathPrefix("/api",
                    HandlerTypePredicate.forAnnotation(RestController.class));
    }
}

Spring WebFlux relies on a parsed representation of the request path called RequestPath for access to decoded path segment values, with semicolon content removed (that is, path or matrix variables). That means, unlike in Spring MVC, you need not indicate whether to decode the request path nor whether to remove semicolon content for path matching purposes.

Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we are also recommend moving away from reliance on it.

Spring WebFlux 依赖于请求路径(叫做RequestPath —— 用于访问已解码的路径段值，其中删除了分号内容（即路径或矩阵变量）)的解析表示。这意味着，与 Spring MVC 不同，您不需要指示是否对请求路径进行解码，也不需要出于路径匹配的目的而删除分号内容。

Spring WebFlux 也不支持后缀模式匹配，这一点不像在 Spring MVC 中，而且我们也建议不要依赖它。

1.11.10. WebSocketService 【网络套接字服务】

The WebFlux Java config declares of a WebSocketHandlerAdapter bean which provides support for the invocation of WebSocket handlers. That means all that remains to do in order to handle a WebSocket handshake request is to map a WebSocketHandler to a URL via SimpleUrlHandlerMapping.

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

In some cases it may be necessary to create the WebSocketHandlerAdapter bean with a provided WebSocketService service which allows configuring WebSocket server properties. For example:

在某些情况下，可能需要使用提供的WebSocketService服务(该服务允许配置 WebSocket 服务器属性)创建WebSocketHandlerAdapterbean，。例如：

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

    @Override
    public WebSocketService getWebSocketService() {
        TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy();
        strategy.setMaxSessionIdleTimeout(0L);
        return new HandshakeWebSocketService(strategy);
    }
}

1.11.11. Advanced Configuration Mode 【高级配置模式】

@EnableWebFlux imports DelegatingWebFluxConfiguration that:

• Provides default Spring configuration for WebFlux applications

• 为 WebFlux 应用程序提供默认的 Spring 配置

• detects and delegates to WebFluxConfigurer implementations to customize that configuration.

• 检测并委托给WebFluxConfigurer实现来自定义配置。

For advanced mode, you can remove @EnableWebFlux and extend directly from DelegatingWebFluxConfiguration instead of implementing WebFluxConfigurer, as the following example shows:

对于高级模式，您可以删除@EnableWebFlux然后直接继承自 DelegatingWebFluxConfiguration而不是实现WebFluxConfigurer，如以下示例所示：

@Configuration
public class WebConfig extends DelegatingWebFluxConfiguration {
    // ...
}

You can keep existing methods in WebConfig, but you can now also override bean declarations from the base class and still have any number of other WebMvcConfigurer implementations on the classpath.

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

1.12. HTTP/2

HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are considerations related to server configuration. For more details, see the HTTP/2 wiki page.

Reactor Netty、Tomcat、Jetty 和 Undertow 支持 HTTP/2。但是，有一些与服务器配置相关的注意事项。有关更多详细信息，请参阅 HTTP/2 wiki 页面。