WebClient 超时设置-工具盒子

1、概览 {#1概览}

WebClient 是一个响应式的 HTTP 客户端，它基于 Reactor 项目提供了函数式 API。

本文将带你了解 WebClient 的超时设置，学习如何正确地设置不同的超时，既包括整个应用程序的全局超时，也包括特定请求的超时。

2、WebClient 和 HTTP 客户端 {#2webclient-和-http-客户端}

WebClient 还需要一个 HTTP 客户端库才能正常工作。Spring 为其中一些提供了内置支持，默认使用的是 Reactor Netty。

大多数配置，包括超时，都可以通过这些客户端完成。

3、通过 HTTP 客户端配置超时 {#3通过-http-客户端配置超时}

如前所述，在应用中设置不同 WebClient 超时的最简单方法是通过底层 HTTP 客户端进行全局设置。这也是最有效的方法。

由于 Netty 是 Spring WebFlux 的默认客户端库，本文将以 Reactor Netty HttpClient 类作为示例。

3.1、响应超时 {#31响应超时}

响应超时是指发送请求后等待接收响应的时间。可以使用 responseTimeout() 方法为客户端配置它：

HttpClient client = HttpClient.create()
  .responseTimeout(Duration.ofSeconds(1));

在本例中，配置的超时时间为 1 秒。Netty 默认不设置响应超时。

然后，就可以使用 HttpClient 来构建 Spring WebClient。

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

之后，WebClient 会继承底层 HttpClient 提供的所有配置，适用于发送的所有请求。

3.2、连接超时 {#32连接超时}

连接超时是客户端和服务器之间建立连接的必须时间段。可以使用不同的 Channel Option Key 和 option() 方法来执行配置：

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

// 创建 WebClient

提供的值以毫秒为单位，将超时设置为 10 秒。Netty 默认值为30 秒。

此外，还可以配置 keep-alive 选项，它可以在连接空闲时发送 TCP 保活探测报文。

HttpClient client = HttpClient.create()
  .option(ChannelOption.SO_KEEPALIVE, true)
  .option(EpollChannelOption.TCP_KEEPIDLE, 300)
  .option(EpollChannelOption.TCP_KEEPINTVL, 60)
  .option(EpollChannelOption.TCP_KEEPCNT, 8);

// 创建 WebClient

如上，启用了 keep-alive，在空闲 5 分钟后以 60 秒为间隔进行探测。还将连接中断前的最大探测次数设置为 8 次。

当连接在给定时间内未建立或被放弃时，会抛出 ConnectTimeoutException 异常。

3.3、读写超时 {#33读写超时}

读取超时发生在一定时间内没有读取数据，而写入超时发生在写入操作无法在特定时间内完成。 HttpClient 允许配置额外的 Handler 来配置这些超时：

HttpClient client = HttpClient.create()
  .doOnConnected(conn -> conn
    .addHandler(new ReadTimeoutHandler(10, TimeUnit.SECONDS))
    .addHandler(new WriteTimeoutHandler(10)));

// 创建 WebClient

通过 doOnConnected() 方法配置连接回调，并在其中添加了 ReadTimeOutHandler 和 WriteTimeOutHandler 实例处理读写超时，超时时间都设置为 10 秒。

这些 Handler 的构造函数接受两种不同的参数。可以指定 TimeUnit 以及对应的值，或者只指定一个值，默认的单位是秒。

底层的 Netty 库提供了 ReadTimeoutException 和 WriteTimeoutException 异常类来表示对应的超时异常。

3.4、SSL/TLS 超时 {#34ssltls-超时}

握手超时是系统在停止操作之前尝试建立 SSL 连接的时间。可以通过 secure() 方法设置 SSL 配置：

HttpClient.create()
  .secure(spec -> spec.sslContext(SslContextBuilder.forClient())
    .defaultConfiguration(SslProvider.DefaultConfigurationType.TCP)
    .handshakeTimeout(Duration.ofSeconds(30))
    .closeNotifyFlushTimeout(Duration.ofSeconds(10))
    .closeNotifyReadTimeout(Duration.ofSeconds(10)));

// 创建 WebClient

如上，将握手超时设置为 30 秒（默认值：10 秒），将 close_notify flush（默认值：3 秒）和 read（默认值：0 秒）超时设置为 10 秒。所有方法都由 SslProvider.Builder 接口提供。

当由于超时而导致握手失败时，将抛出 SslHandshakeTimeoutException。

3.5、代理超时 {#35代理超时}

HttpClient 还支持代理功能。如果与对等端的连接在指定时间内未完成，连接将失败。可以通过 proxy() 设置这个超时时间：

HttpClient.create()
  .proxy(spec -> spec.type(ProxyProvider.Proxy.HTTP)
    .host("proxy")
    .port(8080)
    .connectTimeoutMillis(30000));

// 创建 WebClient

使用 connectTimeoutMillis() 将超时时间设置为 30 秒，默认值为 10 秒。

在连接失败时，Netty 会抛出 ProxyConnectException。

4、请求级超时 {#4请求级超时}

在上一节中，使用 HttpClient 全局配置了不同的超时。不过，也可以独立于全局设置，设置特定请求响应的超时。

4.1、使用 HttpClientRequest 设置响应超时 {#41使用-httpclientrequest-设置响应超时}

在请求级别配置响应超时：

webClient.get()
  .uri("https://baeldung.com/path")
  .httpRequest(httpRequest -> {
    HttpClientRequest reactorRequest = httpRequest.getNativeRequest();
    reactorRequest.responseTimeout(Duration.ofSeconds(2));
  });

如上，使用 WebClient 的 httpRequest() 方法来访问底层 Netty 库的原生 HttpClientRequest。接着，将超时值设置为 2 秒。

该设置会覆盖 HttpClient 层面的任何响应超时设置。也可以将此值设置为 null，以删除任何先前配置的值。

4.2、配置 "响应式流" 超时 {#42配置-响应式流-超时}

Reactor Netty 使用 Reactor Core 作为 Reactive Stream 实现。可以使用 Mono 和 Flux Publisher 提供的 timeout() 方法来配置另一个超时：

webClient.get()
  .uri("https://baeldung.com/path")
  .retrieve()
  .bodyToFlux(JsonNode.class)
  .timeout(Duration.ofSeconds(5));

在这种情况下，如果在 5 秒内没有项目到达，就会出现 TimeoutException 异常。

最好使用 Reactor Netty 中提供的更具体的超时配置选项，因为它们能为特定目的和用例提供更多控制。

timeout() 方法适用于整个操作，包括与远程建立连接到接收响应。它不会覆盖任何与 HttpClient 相关的设置。

5、Exception 处理 {#5exception-处理}

每种类型的超时都会产生一个专门的异常，因此可以使用 Ractive Stream 和 onError 来处理它们：

webClient.get()
  .uri("https://baeldung.com/path")
  .retrieve()
  .bodyToFlux(JsonNode.class)
  .timeout(Duration.ofSeconds(5))
  .onErrorMap(ReadTimeoutException.class, ex -> new HttpTimeoutException("ReadTimeout"))
  .onErrorReturn(SslHandshakeTimeoutException.class, new TextNode("SslHandshakeTimeout"))
  .doOnError(WriteTimeoutException.class, ex -> log.error("WriteTimeout"))
  ...

可以重用之前描述的任何异常，并使用 Reactor 编写自己的处理方法。

此外，还可以根据 HTTP 状态码添加一些逻辑：

webClient.get()
  .uri("https://baeldung.com/path")
  .onStatus(HttpStatus::is4xxClientError, resp -> {
    log.error("ClientError {}", resp.statusCode());
    return Mono.error(new RuntimeException("ClientError"));
  })
  .retrieve()
  .bodyToFlux(JsonNode.class)
  ...