配置

创建 WebClient 的最简单方法是使用以下静态工厂方法之一：

  • WebClient.create()

  • WebClient.create(String baseUrl)

您还可以使用 WebClient.builder() 并带有更多选项：

  • uriBuilderFactory: 用作基本 URL 的自定义 UriBuilderFactory。

  • defaultUriVariables: 展开 URI 模板时使用的默认值。

  • defaultHeader: 每个请求的头部。

  • defaultCookie: 每个请求的 Cookie。

  • defaultRequest: 用于自定义每个请求的 Consumer。

  • filter: 每个请求的客户端过滤器。

  • exchangeStrategies: HTTP 消息读取器/写入器自定义。

  • clientConnector: HTTP 客户端库设置。

  • observationRegistry: 用于启用 可观测性支持 的注册表。

  • observationConvention: 一个可选的自定义约定，用于提取元数据 以进行记录观测。

例如：

  • Java

  • Kotlin

WebClient client = WebClient.builder()
		.codecs(configurer -> ... )
		.build();
val webClient = WebClient.builder()
		.codecs { configurer -> ... }
		.build()

一旦构建，WebClient 是不可变的。但是，您可以克隆它并构建一个修改后的副本，如下所示：

  • Java

  • Kotlin

WebClient client1 = WebClient.builder()
		.filter(filterA).filter(filterB).build();

WebClient client2 = client1.mutate()
		.filter(filterC).filter(filterD).build();

// client1 has filterA, filterB

// client2 has filterA, filterB, filterC, filterD
val client1 = WebClient.builder()
		.filter(filterA).filter(filterB).build()

val client2 = client1.mutate()
		.filter(filterC).filter(filterD).build()

// client1 has filterA, filterB

// client2 has filterA, filterB, filterC, filterD

MaxInMemorySize

为了避免应用程序内存问题，编解码器对内存中的数据缓冲 有大小限制。默认情况下，这些限制设置为 256KB。 如果这不够用，您将收到以下错误：

org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on max bytes to buffer

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

  • Java

  • Kotlin

WebClient webClient = WebClient.builder()
		.codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024))
		.build();
val webClient = WebClient.builder()
		.codecs { configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) }
		.build()

Reactor Netty

要自定义 Reactor Netty 设置，请提供一个预配置的 HttpClient：

  • Java

  • Kotlin

HttpClient httpClient = HttpClient.create().secure(sslSpec -> ...);

WebClient webClient = WebClient.builder()
		.clientConnector(new ReactorClientHttpConnector(httpClient))
		.build();
val httpClient = HttpClient.create().secure { ... }

val webClient = WebClient.builder()
	.clientConnector(ReactorClientHttpConnector(httpClient))
	.build()

资源

默认情况下，HttpClient 参与 reactor.netty.http.HttpResources 中持有的全局 Reactor Netty 资源，包括事件循环线程和连接池。 这是推荐的模式，因为对于事件循环并发，固定、共享的资源是首选。在此模式下，全局资源在进程退出之前保持活动状态。

如果服务器与进程同时计时，通常无需显式关闭。但是，如果服务器可以在进程内启动或停止（例如，部署为 WAR 的 Spring MVC 应用程序），您可以声明一个类型为 ReactorResourceFactory 且 globalResources=true（默认值）的 Spring 管理 Bean，以确保在 Spring ApplicationContext 关闭时关闭 Reactor Netty 全局资源，如以下示例所示：

  • Java

  • Kotlin

@Bean
public ReactorResourceFactory reactorResourceFactory() {
	return new ReactorResourceFactory();
}
@Bean
fun reactorResourceFactory() = ReactorResourceFactory()

您也可以选择不参与全局 Reactor Netty 资源。但是，在此模式下，确保所有 Reactor Netty 客户端和服务器实例都使用共享资源的负担在于您，如以下示例所示：

Java
@Bean
public ReactorResourceFactory resourceFactory() {
	ReactorResourceFactory factory = new ReactorResourceFactory();
	factory.setUseGlobalResources(false); [id="CO1-1"][id="CO1-1"][id="CO1-1"](1)
	return factory;
}

@Bean
public WebClient webClient() {

	Function<HttpClient, HttpClient> mapper = client -> {
		// Further customizations...
	};

	ClientHttpConnector connector =
			new ReactorClientHttpConnector(resourceFactory(), mapper); [id="CO1-2"][id="CO1-2"][id="CO1-2"](2)

	return WebClient.builder().clientConnector(connector).build(); [id="CO1-3"][id="CO1-3"][id="CO1-3"](3)
}
<1>  创建独立于全局的资源。
<1>  使用带有资源工厂的 `ReactorClientHttpConnector` 构造函数。
<1>  将连接器插入 `WebClient.Builder`。
Kotlin
@Bean
fun resourceFactory() = ReactorResourceFactory().apply {
	isUseGlobalResources = false [id="CO2-1"][id="CO1-4"][id="CO2-1"](1)
}

@Bean
fun webClient(): WebClient {

	val mapper: (HttpClient) -> HttpClient = {
		// Further customizations...
	}

	val connector = ReactorClientHttpConnector(resourceFactory(), mapper) [id="CO2-2"][id="CO1-5"][id="CO2-2"](2)

	return WebClient.builder().clientConnector(connector).build() [id="CO2-3"][id="CO1-6"][id="CO2-3"](3)
}
<1>  创建独立于全局的资源。
<1>  使用带有资源工厂的 `ReactorClientHttpConnector` 构造函数。
<1>  将连接器插入 `WebClient.Builder`。

超时

要配置连接超时：

  • Java

  • Kotlin

import io.netty.channel.ChannelOption;

HttpClient httpClient = HttpClient.create()
		.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);

WebClient webClient = WebClient.builder()
		.clientConnector(new ReactorClientHttpConnector(httpClient))
		.build();
import io.netty.channel.ChannelOption

val httpClient = HttpClient.create()
		.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);

val webClient = WebClient.builder()
		.clientConnector(ReactorClientHttpConnector(httpClient))
		.build();

要配置读取或写入超时：

  • Java

  • Kotlin

import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.handler.timeout.WriteTimeoutHandler;

HttpClient httpClient = HttpClient.create()
		.doOnConnected(conn -> conn
				.addHandlerLast(new ReadTimeoutHandler(10))
				.addHandlerLast(new WriteTimeoutHandler(10)));

// Create WebClient...
import io.netty.handler.timeout.ReadTimeoutHandler
import io.netty.handler.timeout.WriteTimeoutHandler

val httpClient = HttpClient.create()
		.doOnConnected { conn -> conn
				.addHandlerLast(ReadTimeoutHandler(10))
				.addHandlerLast(WriteTimeoutHandler(10))
		}

// Create WebClient...

要配置所有请求的响应超时：

  • Java

  • Kotlin

HttpClient httpClient = HttpClient.create()
		.responseTimeout(Duration.ofSeconds(2));

// Create WebClient...
val httpClient = HttpClient.create()
		.responseTimeout(Duration.ofSeconds(2));

// Create WebClient...

要配置特定请求的响应超时：

  • Java

  • Kotlin

WebClient.create().get()
		.uri("https://example.org/path")
		.httpRequest(httpRequest -> {
			HttpClientRequest reactorRequest = httpRequest.getNativeRequest();
			reactorRequest.responseTimeout(Duration.ofSeconds(2));
		})
		.retrieve()
		.bodyToMono(String.class);
WebClient.create().get()
		.uri("https://example.org/path")
		.httpRequest { httpRequest: ClientHttpRequest ->
			val reactorRequest = httpRequest.getNativeRequest<HttpClientRequest>()
			reactorRequest.responseTimeout(Duration.ofSeconds(2))
		}
		.retrieve()
		.bodyToMono(String::class.java)

JDK HttpClient

以下示例展示了如何自定义 JDK HttpClient：

  • Java

  • Kotlin

HttpClient httpClient = HttpClient.newBuilder()
	.followRedirects(Redirect.NORMAL)
	.connectTimeout(Duration.ofSeconds(20))
	.build();

ClientHttpConnector connector =
		new JdkClientHttpConnector(httpClient, new DefaultDataBufferFactory());

WebClient webClient = WebClient.builder().clientConnector(connector).build();
val httpClient = HttpClient.newBuilder()
	.followRedirects(Redirect.NORMAL)
	.connectTimeout(Duration.ofSeconds(20))
	.build()

val connector = JdkClientHttpConnector(httpClient, DefaultDataBufferFactory())

val webClient = WebClient.builder().clientConnector(connector).build()

Jetty

以下示例展示了如何自定义 Jetty HttpClient 设置：

  • Java

  • Kotlin

HttpClient httpClient = new HttpClient();
httpClient.setCookieStore(...);

WebClient webClient = WebClient.builder()
		.clientConnector(new JettyClientHttpConnector(httpClient))
		.build();
val httpClient = HttpClient()
httpClient.cookieStore = ...

val webClient = WebClient.builder()
		.clientConnector(JettyClientHttpConnector(httpClient))
		.build();

默认情况下，HttpClient 创建自己的资源（Executor、ByteBufferPool、Scheduler），这些资源在进程退出或调用 stop() 之前保持活动状态。

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

Java
@Bean
public JettyResourceFactory resourceFactory() {
	return new JettyResourceFactory();
}

@Bean
public WebClient webClient() {

	HttpClient httpClient = new HttpClient();
	// Further customizations...

	ClientHttpConnector connector =
			new JettyClientHttpConnector(httpClient, resourceFactory()); [id="CO3-1"]1

	return WebClient.builder().clientConnector(connector).build(); [id="CO3-2"]2
}
<1>  使用带有资源工厂的 `JettyClientHttpConnector` 构造函数。
<1>  将连接器插入 `WebClient.Builder`。
Kotlin
@Bean
fun resourceFactory() = JettyResourceFactory()

@Bean
fun webClient(): WebClient {

	val httpClient = HttpClient()
	// Further customizations...

	val connector = JettyClientHttpConnector(httpClient, resourceFactory()) [id="CO4-1"][id="CO1-7"][id="CO4-1"](1)

	return WebClient.builder().clientConnector(connector).build() [id="CO4-2"][id="CO1-8"][id="CO4-2"](2)
}
<1>  使用带有资源工厂的 `JettyClientHttpConnector` 构造函数。
<1>  将连接器插入 `WebClient.Builder`。

HttpComponents

以下示例展示了如何自定义 Apache HttpComponents HttpClient 设置：

  • Java

  • Kotlin

HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom();
clientBuilder.setDefaultRequestConfig(...);
CloseableHttpAsyncClient client = clientBuilder.build();

ClientHttpConnector connector = new HttpComponentsClientHttpConnector(client);

WebClient webClient = WebClient.builder().clientConnector(connector).build();
val client = HttpAsyncClients.custom().apply {
	setDefaultRequestConfig(...)
}.build()
val connector = HttpComponentsClientHttpConnector(client)
val webClient = WebClient.builder().clientConnector(connector).build()