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 頁面。