Reactive Core

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

  • 对于服务器请求处理，有两层支持。

    • HttpHandler：使用非阻塞 I/O 和 Reactive Streams 反压处理 HTTP 请求的基本契约，以及对 Reactor Netty、Tomcat、Jetty 和任何 Servlet 容器的适配器。

    • WebHandler API：更高层、通用的 Web API，用于请求处理，其上构建了具体的编程模型，如带注解的控制器和函数式端点。

  • 在客户端，有一个基本的 ClientHttpConnector 契约，用于使用非阻塞 I/O 和 Reactive Streams 反压执行 HTTP 请求，以及对 Reactor Netty、响应式 Jetty HttpClient 和 Apache HttpComponents 的适配器。应用程序中使用的更高级别的 WebClient 构建在此基本契约之上。

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

HttpHandler

HttpHandler 是一个简单的契约，只有一个方法来处理请求和响应。它刻意保持最小化，其主要也是唯一目的是作为不同 HTTP 服务器 API 的最小抽象。

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

服务器名称 使用的服务器 API Reactive Streams 支持

Netty

Netty API

Reactor Netty

Tomcat

Servlet 非阻塞 I/O；Tomcat API 用于读写 ByteBuffers 而不是 byte[]

spring-web: Servlet 非阻塞 I/O 到 Reactive Streams 桥接

Jetty

Servlet 非阻塞 I/O；Jetty API 用于写入 ByteBuffers 而不是 byte[]

spring-web: Servlet 非阻塞 I/O 到 Reactive Streams 桥接

Servlet 容器

Servlet 非阻塞 I/O

spring-web: Servlet 非阻塞 I/O 到 Reactive Streams 桥接

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

服务器名称 组 ID Artifact 名称

Reactor Netty

io.projectreactor.netty

reactor-netty

Tomcat

org.apache.tomcat.embed

tomcat-embed-core

Jetty

org.eclipse.jetty

jetty-server, jetty-servlet

以下代码片段展示了如何将 HttpHandler 适配器与每个服务器 API 配合使用。

Reactor Netty

  • Java

  • Kotlin

HttpHandler handler = ...
ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);
HttpServer.create().host(host).port(port).handle(adapter).bindNow();
val handler: HttpHandler = ...
val adapter = ReactorHttpHandlerAdapter(handler)
HttpServer.create().host(host).port(port).handle(adapter).bindNow()

Tomcat

  • Java

  • Kotlin

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();
val handler: HttpHandler = ...
val servlet = TomcatHttpHandlerAdapter(handler)

val server = Tomcat()
val base = File(System.getProperty("java.io.tmpdir"))
val rootContext = server.addContext("", base.absolutePath)
Tomcat.addServlet(rootContext, "main", servlet)
rootContext.addServletMappingDecoded("/", "main")
server.host = host
server.setPort(port)
server.start()

Jetty

  • Java

  • Kotlin

HttpHandler handler = ...
JettyCoreHttpHandlerAdapter adapter = new JettyCoreHttpHandlerAdapter(handler);

Server server = new Server();
server.setHandler(adapter);

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

server.start();
val handler: HttpHandler = ...
val adapter = JettyCoreHttpHandlerAdapter(handler)

val server = Server()
server.setHandler(adapter)

val connector = ServerConnector(server)
connector.host = host
connector.port = port
server.addConnector(connector)

server.start()
在 Spring Framework 6.2 中，JettyHttpHandlerAdapter 已被弃用，转而使用 JettyCoreHttpHandlerAdapter，后者直接与 Jetty 12 API 集成，无需 Servlet 层。

若要部署为 WAR 到 Servlet 容器，请使用 AbstractReactiveWebInitializer，通过 ServletHttpHandlerAdapter 将 HttpHandler 适配到 Servlet。

WebHandler API

org.springframework.web.server 包基于 HttpHandler 契约构建，提供了一个通用的 Web API，通过多个 WebExceptionHandler、多个 WebFilter 和一个 WebHandler 组件链来处理请求。该链可以通过 WebHttpHandlerBuilder 组装，只需指向一个 Spring ApplicationContext，其中组件会被自动检测，和/或通过构建器注册组件。

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

  • 带有属性的用户会话。

  • 请求属性。

  • 请求已解析的 Locale 或 Principal。

  • 访问已解析和缓存的表单数据。

  • 多部分数据的抽象。

  • 等等...

特殊 Bean 类型

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

Bean 名称 Bean 类型 计数 描述

<任意>

WebExceptionHandler

0..N

为 WebFilter 实例链和目标 WebHandler 中的异常提供处理。有关更多详细信息，请参见 异常。

<任意>

WebFilter

0..N

在过滤链的其余部分和目标 WebHandler 之前和之后应用拦截式逻辑。有关更多详细信息，请参见 过滤器。

webHandler

WebHandler

1

请求的处理程序。

webSessionManager

WebSessionManager

0..1

通过 ServerWebExchange 上的方法公开的 WebSession 实例管理器。默认为 DefaultWebSessionManager。

serverCodecConfigurer

ServerCodecConfigurer

0..1

用于访问 HttpMessageReader 实例，以解析表单数据和多部分数据，然后通过 ServerWebExchange 上的方法公开。默认为 ServerCodecConfigurer.create()。

localeContextResolver

LocaleContextResolver

0..1

通过 ServerWebExchange 上的方法公开的 LocaleContext 解析器。默认为 AcceptHeaderLocaleContextResolver。

forwardedHeaderTransformer

ForwardedHeaderTransformer

0..1

用于处理转发类型头，可以提取并删除它们，也可以只删除它们。默认不使用。

表单数据

ServerWebExchange 公开了以下用于访问表单数据的方法

  • Java

  • Kotlin

Mono<MultiValueMap<String, String>> getFormData();
suspend fun getFormData(): MultiValueMap<String, String>

DefaultServerWebExchange 使用配置的 HttpMessageReader 将表单数据（application/x-www-form-urlencoded）解析为 MultiValueMap。默认情况下，FormHttpMessageReader 配置为由 ServerCodecConfigurer bean 使用（参见 Web Handler API）。

多部分数据

查看 Servlet 栈中的等效内容

ServerWebExchange 公开了以下用于访问多部分数据的方法

  • Java

  • Kotlin

Mono<MultiValueMap<String, Part>> getMultipartData();
suspend fun getMultipartData(): MultiValueMap<String, Part>

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

要以流式方式解析多部分数据，可以使用 PartEventHttpMessageReader 返回的 Flux<PartEvent>，而不是使用 @RequestPart，因为后者意味着按名称对单个部分进行类似 Map 的访问，因此需要完整解析多部分数据。相反，可以使用 @RequestBody 将内容解码为 Flux<PartEvent>，而无需收集到 MultiValueMap。

转发头

查看 Servlet 栈中的等效内容

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

RFC 7239 定义了 Forwarded HTTP 头，代理可以使用它来提供有关原始请求的信息。

非标准头

还有其他非标准头，包括 X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-Proto、X-Forwarded-Ssl、X-Forwarded-Prefix 和 X-Forwarded-For。

X-Forwarded-Host

虽然不是标准，但 X-Forwarded-Host: <host> 是一个事实上的标准头，用于将原始主机传递给下游服务器。例如，如果向代理发送一个 example.com/resource 的请求，该代理将请求转发到 localhost:8080/resource，则可以发送一个 X-Forwarded-Host: example.com 的头，以告知服务器原始主机是 example.com。

X-Forwarded-Port

虽然不是标准，但 X-Forwarded-Port: <port> 是一个事实上的标准头，用于将原始端口传递给下游服务器。例如，如果向代理发送一个 example.com/resource 的请求，该代理将请求转发到 localhost:8080/resource，则可以发送一个 X-Forwarded-Port: 443 的头，以告知服务器原始端口是 443。

X-Forwarded-Proto

虽然不是标准，但 X-Forwarded-Proto: (https|http) 是一个事实上的标准头，用于将原始协议（例如 https / http）传递给下游服务器。例如，如果向代理发送一个 example.com/resource 的请求，该代理将请求转发到 localhost:8080/resource，则可以发送一个 X-Forwarded-Proto: https 的头，以告知服务器原始协议是 https。

X-Forwarded-Ssl

虽然不是标准，但 X-Forwarded-Ssl: (on|off) 是一个事实上的标准头，用于将原始协议（例如 https / https）传递给下游服务器。例如，如果向代理发送一个 example.com/resource 的请求，该代理将请求转发到 localhost:8080/resource，则可以发送一个 X-Forwarded-Ssl: on 的头，以告知服务器原始协议是 https。

X-Forwarded-Prefix

虽然不是标准，但 X-Forwarded-Prefix: <prefix> 是一个事实上的标准头，用于将原始 URL 路径前缀传递给下游服务器。

X-Forwarded-Prefix 的使用可能因部署场景而异，需要灵活地允许替换、删除或前置目标服务器的路径前缀。

场景 1：覆盖路径前缀

https://example.com/api/{path} -> https://:8080/app1/{path}

前缀是捕获组 {path} 之前的路径起始部分。对于代理，前缀是 /api，而对于服务器，前缀是 /app1。在这种情况下，代理可以发送 X-Forwarded-Prefix: /api，以使原始前缀 /api 覆盖服务器前缀 /app1。

场景 2：删除路径前缀

有时，应用程序可能希望删除前缀。例如，考虑以下代理到服务器的映射

https://app1.example.com/{path} -> https://:8080/app1/{path}
https://app2.example.com/{path} -> https://:8080/app2/{path}

代理没有前缀，而应用程序 app1 和 app2 分别有路径前缀 /app1 和 /app2。代理可以发送 X-Forwarded-Prefix: ，以使空前缀覆盖服务器前缀 /app1 和 /app2。

这种部署场景的一个常见情况是，每个生产应用服务器都需要支付许可费用，并且最好在每个服务器上部署多个应用程序以减少费用。另一个原因是在同一服务器上运行更多应用程序，以共享服务器运行所需的资源。

在这些场景中，应用程序需要一个非空的上下文根，因为同一服务器上存在多个应用程序。但是，这不应该在公共 API 的 URL 路径中可见，其中应用程序可以使用不同的子域，这提供了以下好处：

  • 增加安全性，例如同源策略

  • 应用程序的独立扩展（不同域指向不同 IP 地址）

场景 3：插入路径前缀

在其他情况下，可能需要前置一个前缀。例如，考虑以下代理到服务器的映射

https://example.com/api/app1/{path} -> https://:8080/app1/{path}

在这种情况下，代理的前缀是 /api/app1，服务器的前缀是 /app1。代理可以发送 X-Forwarded-Prefix: /api/app1，以使原始前缀 /api/app1 覆盖服务器前缀 /app1。

X-Forwarded-For

X-Forwarded-For: <address> 是一个事实上的标准头，用于将客户端的原始 InetSocketAddress 传递给下游服务器。例如，如果客户端在 [fd00:fefe:1::4] 向 192.168.0.1 的代理发送请求，HTTP 请求中包含的“远程地址”信息将反映客户端的实际地址，而不是代理的地址。

ForwardedHeaderTransformer

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

安全考虑

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

过滤器

查看 Servlet 栈中的等效内容

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

CORS

查看 Servlet 栈中的等效内容

Spring WebFlux 通过控制器上的注解提供对 CORS 配置的精细支持。但是，当您将其与 Spring Security 一起使用时，我们建议依赖内置的 CorsFilter，它必须在 Spring Security 过滤器链之前进行排序。

有关更多详细信息，请参见 CORS 部分和 CORS WebFilter。

URL 处理程序

查看 Servlet 栈中的等效内容

您可能希望控制器端点匹配 URL 路径中带或不带尾随斜杠的路由。例如，"GET /home" 和 "GET /home/" 都应该由使用 @GetMapping("/home") 注解的控制器方法处理。

将尾随斜杠变体添加到所有映射声明中并不是处理此用例的最佳方法。UrlHandlerFilter web 过滤器就是为此目的而设计的。它可以配置为

  • 当接收到带有尾随斜杠的 URL 时，用 HTTP 重定向状态响应，将浏览器发送到不带尾随斜杠的 URL 变体。

  • 改变请求，使其表现得好像请求是未带尾随斜杠发送的，并继续处理请求。

以下是如何为博客应用程序实例化和配置 UrlHandlerFilter 的示例

  • Java

  • Kotlin

UrlHandlerFilter urlHandlerFilter = UrlHandlerFilter
		// will HTTP 308 redirect "/blog/my-blog-post/" -> "/blog/my-blog-post"
		.trailingSlashHandler("/blog/**").redirect(HttpStatus.PERMANENT_REDIRECT)
		// will mutate the request to "/admin/user/account/" and make it as "/admin/user/account"
		.trailingSlashHandler("/admin/**").mutateRequest()
		.build();
val urlHandlerFilter = UrlHandlerFilter
	// will HTTP 308 redirect "/blog/my-blog-post/" -> "/blog/my-blog-post"
	.trailingSlashHandler("/blog/**").redirect(HttpStatus.PERMANENT_REDIRECT)
	// will mutate the request to "/admin/user/account/" and make it as "/admin/user/account"
	.trailingSlashHandler("/admin/**").mutateRequest()
	.build()

异常

查看 Servlet 栈中的等效内容

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

下表描述了可用的 WebExceptionHandler 实现

异常处理程序 描述

ResponseStatusExceptionHandler

通过将响应设置为异常的 HTTP 状态码，为 ResponseStatusException 类型的异常提供处理。

WebFluxResponseStatusExceptionHandler

ResponseStatusExceptionHandler 的扩展，它还可以确定任何异常上 @ResponseStatus 注解的 HTTP 状态码。

此处理程序在 WebFlux 配置 中声明。

编解码器

查看 Servlet 栈中的等效内容

spring-web 和 spring-core 模块通过非阻塞 I/O 和 Reactive Streams 反压，支持将字节内容序列化和反序列化为高级对象。以下描述了此支持

  • Encoder 和 Decoder 是独立于 HTTP 对内容进行编码和解码的低级契约。

  • HttpMessageReader 和 HttpMessageWriter 是用于编码和解码 HTTP 消息内容的契约。

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

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

spring-core 模块提供了 byte[]、ByteBuffer、DataBuffer、Resource 和 String 编码器和解码器实现。spring-web 模块提供了 Jackson JSON、Jackson Smile、JAXB2、Protocol Buffers 和其他编码器和解码器，以及用于表单数据、多部分内容、服务器发送事件等的 Web 专用 HTTP 消息读取器和写入器实现。

ClientCodecConfigurer 和 ServerCodecConfigurer 通常用于配置和自定义应用程序中使用的编解码器。请参见配置 HTTP 消息编解码器 的部分。

Jackson JSON

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

Jackson2Decoder 的工作方式如下

  • Jackson 的异步、非阻塞解析器用于将字节块流聚合为表示 JSON 对象的 TokenBuffer。

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

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

  • 当解码为多值发布者（例如 Flux）时，一旦收到足够形成完整对象的字节，每个 TokenBuffer 就会传递给 ObjectMapper。输入内容可以是 JSON 数组，或任何行分隔 JSON 格式，如 NDJSON、JSON Lines 或 JSON Text Sequences。

Jackson2Encoder 的工作方式如下

  • 对于单值发布者（例如 Mono），只需通过 ObjectMapper 对其进行序列化。

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

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

  • 对于 SSE，Jackson2Encoder 会针对每个事件调用，并刷新输出以确保及时交付。

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

表单数据

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

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

一旦使用了 getFormData()，就不能再从请求体中读取原始原始内容。因此，应用程序应该始终通过 ServerWebExchange 访问缓存的表单数据，而不是从原始请求体中读取。

多部分

MultipartHttpMessageReader 和 MultipartHttpMessageWriter 支持解码和编码“multipart/form-data”、“multipart/mixed”和“multipart/related”内容。反过来，MultipartHttpMessageReader 将实际解析委托给另一个 HttpMessageReader，以解析为 Flux<Part>，然后简单地将部分收集到 MultiValueMap 中。默认情况下，使用 DefaultPartHttpMessageReader，但这可以通过 ServerCodecConfigurer 更改。有关 DefaultPartHttpMessageReader 的更多信息，请参阅 DefaultPartHttpMessageReader 的 Javadoc。

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

一旦使用了 getMultipartData()，就不能再从请求体中读取原始原始内容。因此，应用程序必须始终使用 getMultipartData() 进行重复的、类似 map 的部分访问，否则依赖于 SynchronossPartHttpMessageReader 进行一次性的 Flux<Part> 访问。

Protocol Buffers

ProtobufEncoder 和 ProtobufDecoder 支持对 com.google.protobuf.Message 类型进行“application/x-protobuf”、“application/octet-stream”和“application/vnd.google.protobuf”内容的解码和编码。如果内容是随内容类型（例如“application/x-protobuf;delimited=true”）接收/发送，并且带有“delimited”参数，它们还支持值的流。这需要“com.google.protobuf:protobuf-java”库，版本 3.29 及更高。

ProtobufJsonDecoder 和 ProtobufJsonEncoder 变体支持读写 JSON 文档到 Protobuf 消息。它们需要“com.google.protobuf:protobuf-java-util”依赖项。请注意，JSON 变体不支持读取消息流，有关更多详细信息，请参阅 ProtobufJsonDecoder 的 Javadoc。

Google Gson

应用程序可以使用 GsonEncoder 和 GsonDecoder，借助 Google Gson 库来序列化和反序列化 JSON 文档。此编解码器支持 JSON 媒体类型和用于流的 NDJSON 格式。

Gson 不支持非阻塞解析，因此 GsonDecoder 不支持反序列化为 Flux<*> 类型。例如，如果此解码器用于反序列化 JSON 流甚至作为 Flux<*> 的元素列表，则会在运行时抛出 UnsupportedOperationException。应用程序应该转而专注于反序列化有界集合，并使用 Mono<List<*>> 作为目标类型。

限制

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

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

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

流

查看 Servlet 栈中的等效内容

当流式传输到 HTTP 响应时（例如，text/event-stream、application/x-ndjson），定期发送数据很重要，以便更快更可靠地检测到断开连接的客户端。这种发送可以是只包含注释的空 SSE 事件或任何其他“无操作”数据，这些数据实际上可以用作心跳。

DataBuffer

DataBuffer 是 WebFlux 中字节缓冲区的表示。此参考的 Spring Core 部分在 数据缓冲区和编解码器 部分对此有更多介绍。要理解的关键点是，在某些服务器（如 Netty）上，字节缓冲区是池化的并具有引用计数，并且在消耗后必须释放以避免内存泄漏。

WebFlux 应用程序通常不需要担心这些问题，除非它们直接消耗或生成数据缓冲区，而不是依赖编解码器转换为高级对象，或者除非它们选择创建自定义编解码器。对于这种情况，请查看 数据缓冲区和编解码器 中的信息，特别是 使用 DataBuffer 部分。

日志

查看 Servlet 栈中的等效内容

Spring WebFlux 中的 DEBUG 级别日志记录被设计为紧凑、最小且人性化。它侧重于反复有用的高价值信息位，而不是只在调试特定问题时有用的信息。

TRACE 级别日志记录通常遵循与 DEBUG 相同的原则（例如，它也不应该是信息洪流），但可用于调试任何问题。此外，一些日志消息在 TRACE 级别和 DEBUG 级别可能显示不同的详细程度。

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

日志 ID

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

在服务器端，日志 ID 存储在 ServerWebExchange 属性中（LOG_ID_ATTRIBUTE），而基于该 ID 的完整格式化前缀可从 ServerWebExchange#getLogPrefix() 获取。在 WebClient 端，日志 ID 存储在 ClientRequest 属性中（LOG_ID_ATTRIBUTE），而完整格式化前缀可从 ClientRequest#logPrefix() 获取。

敏感数据

查看 Servlet 栈中的等效内容

DEBUG 和 TRACE 日志记录可以记录敏感信息。这就是为什么表单参数和头默认被掩盖，并且您必须显式启用它们的完整日志记录。

以下示例展示了如何为服务器端请求执行此操作

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
class MyConfig implements WebFluxConfigurer {

	@Override
	public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
		configurer.defaultCodecs().enableLoggingRequestDetails(true);
	}
}
@Configuration
@EnableWebFlux
class MyConfig : WebFluxConfigurer {

	override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) {
		configurer.defaultCodecs().enableLoggingRequestDetails(true)
	}
}

以下示例展示了如何为客户端请求执行此操作

  • Java

  • Kotlin

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

WebClient webClient = WebClient.builder()
		.exchangeStrategies(strategies -> strategies.codecs(consumer))
		.build();
val consumer: (ClientCodecConfigurer) -> Unit  = { configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true) }

val webClient = WebClient.builder()
		.exchangeStrategies({ strategies -> strategies.codecs(consumer) })
		.build()

附加器

SLF4J 和 Log4J 2 等日志库提供了避免阻塞的异步日志器。虽然它们有自己的缺点，例如可能丢弃无法排队进行日志记录的消息，但它们是目前在响应式、非阻塞应用程序中使用的最佳可用选项。

自定义编解码器

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

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

以下示例展示了如何为客户端请求执行此操作

  • Java

  • Kotlin

WebClient webClient = WebClient.builder()
		.codecs(configurer -> {
			CustomDecoder decoder = new CustomDecoder();
			configurer.customCodecs().registerWithDefaultConfig(decoder);
		})
		.build();
val webClient = WebClient.builder()
		.codecs({ configurer ->
			val decoder = CustomDecoder()
			configurer.customCodecs().registerWithDefaultConfig(decoder)
		 })
		.build()
© . This site is unofficial and not affiliated with VMware.