跳到主要内容

配置

ChatGPT-4o 中英对照 Configuration

创建 WebClient 最简单的方法是通过静态工厂方法之一：

  • WebClient.create()

  • WebClient.create(String baseUrl)

你也可以使用 WebClient.builder() 进行更多选项的配置：

  • uriBuilderFactory：自定义的 UriBuilderFactory 用作基础 URL。

  • defaultUriVariables：扩展 URI 模板时使用的默认值。

  • defaultHeader：每个请求的头信息。

  • defaultCookie：每个请求的 Cookie。

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

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

  • exchangeStrategies：HTTP 消息读取器/写入器的自定义设置。

  • clientConnector：HTTP 客户端库设置。

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

  • observationConvention：一个可选的，自定义的约定，用于提取元数据以记录观察结果。

例如：

WebClient client = WebClient.builder()
        .codecs(configurer -> ... )
        .build();
java

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

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
java

MaxInMemorySize​

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

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

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

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

Reactor Netty​

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

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

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

资源​

默认情况下，HttpClient 参与由 reactor.netty.http.HttpResources 持有的全局 Reactor Netty 资源，包括事件循环线程和连接池。这是推荐的模式，因为固定的共享资源更适合事件循环的并发。在这种模式下，全局资源会保持活跃直到进程退出。

如果服务器与进程同步，通常不需要显式关闭。然而，如果服务器可以在进程中启动或停止（例如，作为 WAR 部署的 Spring MVC 应用程序），您可以声明一个 ReactorResourceFactory 类型的 Spring 管理 bean，并设置 globalResources=true（默认值），以确保在 Spring ApplicationContext 关闭时，Reactor Netty 的全局资源也被关闭，如以下示例所示：

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

您也可以选择不参与全局 Reactor Netty 资源。然而，在这种模式下，您需要确保所有 Reactor Netty 客户端和服务器实例使用共享资源，如以下示例所示：

@Bean
public ReactorResourceFactory resourceFactory() {
    ReactorResourceFactory factory = new ReactorResourceFactory();
    factory.setUseGlobalResources(false); 1
    return factory;
}

@Bean
public WebClient webClient() {

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

    ClientHttpConnector connector =
            new ReactorClientHttpConnector(resourceFactory(), mapper); 2

    return WebClient.builder().clientConnector(connector).build(); 3
}
java

  • 创建独立于全局资源的资源。

  • 使用带有资源工厂的 ReactorClientHttpConnector 构造函数。

  • 将连接器插入到 WebClient.Builder 中。

超时​

配置连接超时：

import io.netty.channel.ChannelOption;

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

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

配置读取或写入超时：

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

为所有请求配置响应超时：

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

// Create WebClient...
java

为特定请求配置响应超时：

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

JDK HttpClient​

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

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

Jetty​

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

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

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

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

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

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

@Bean
public WebClient webClient() {

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

    ClientHttpConnector connector =
            new JettyClientHttpConnector(httpClient, resourceFactory()); 1

    return WebClient.builder().clientConnector(connector).build(); 2
}
java

  • 使用带有资源工厂的 JettyClientHttpConnector 构造函数。

  • 将连接器插入到 WebClient.Builder 中。

HttpComponents​

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

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

ClientHttpConnector connector = new HttpComponentsClientHttpConnector(client);

WebClient webClient = WebClient.builder().clientConnector(connector).build();
java