如何为Spring Webflux默认WebClient设置连接超时？

我来帮你梳理清楚WebClient超时配置的关键点，以及你关心的几个问题：

一、正确设置默认超时的方式 #

WebClient基于Reactor Netty实现，所以要设置全局默认超时，必须从底层HttpClient入手，配置TCP连接和响应相关的超时参数，这样才能保证超时后资源被正确释放。

推荐两种配置方式，根据你的Spring WebFlux/Reactor Netty版本选择：

方式1：基于Netty Handler的配置（兼容旧版本） #

import io.netty.channel.ChannelOption;
import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.handler.timeout.WriteTimeoutHandler;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;

WebClient webClient = WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(HttpClient.create()
                // 设置TCP连接超时（单位：毫秒）
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
                // 连接建立后，添加读写超时Handler（单位：秒）
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(10))
                        .addHandlerLast(new WriteTimeoutHandler(10)))))
        .baseUrl("https://your-api-base-url.com")
        .build();

方式2：Reactor Netty简化API配置（新版本推荐） #

如果你的Reactor Netty版本在0.9.6+，可以用更简洁的API：

import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;
import java.time.Duration;

WebClient webClient = WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(HttpClient.create()
                .connectTimeout(Duration.ofSeconds(5)) // 连接超时5秒
                .responseTimeout(Duration.ofSeconds(10)))) // 响应读取超时10秒
        .baseUrl("https://your-api-base-url.com")
        .build();

这两种配置都是全局生效的，所有通过该WebClient发起的请求都会遵循这些超时规则，且超时后底层会自动关闭连接、释放资源。

二、仅使用Mono#timeout(Duration)是否足够？ #

绝对不够。

Mono#timeout是上层的信号超时——它只关注Mono是否在指定时间内发出完成/错误信号，并不会主动取消底层的HTTP请求或关闭连接。举个例子：
你调用webClient.get().retrieve().bodyToMono(User.class).timeout(Duration.ofSeconds(3))，3秒后上层Mono会抛出TimeoutException，但底层的Reactor Netty请求可能还在等待服务器响应，连接依然被占用。

这种上层超时只是“放弃等待结果”，并没有真正终止请求，完全起不到资源保护的作用。

三、是否会导致内存或连接泄漏？ #

是的，如果只依赖Mono#timeout而不配置底层HttpClient超时，大概率会出现连接泄漏和内存占用过高的问题。

底层的请求线程、连接池中的连接会被持续占用，直到请求自然完成（可能等待很久），或者连接池被耗尽，新的请求无法发起。长期积累下来，会导致服务资源耗尽、响应变慢。

正确的做法是：先配置底层HttpClient的全局超时作为兜底，再针对个别需要自定义超时的请求叠加Mono#timeout——这样即使上层超时，底层也会在自己的超时时间内强制关闭连接。

四、关于你提到的“之前解决方案无效”的可能原因 #

如果之前尝试的配置没生效，不妨排查这几点：

• 你是否用配置后的WebClient.Builder创建了实例？比如是不是误写了WebClient.create()而没有用自己构建的builder？
• 是否混淆了连接超时和读取超时的配置方式？比如把读取超时配置成了连接超时？
• 版本兼容性问题：不同版本的Reactor Netty/WebFlux的API有变化，比如旧版本不支持responseTimeout方法，需要用ReadTimeoutHandler。

内容的提问来源于stack exchange，提问作者Justus87