Java WebClient如何不新建实例为单个请求设置连接超时

不需要每次新建WebClient实例，利用Reactor Netty（Spring WebClient默认底层客户端）的上下文透传+连接阶段回调能力，只需要初始化一次全局WebClient，就能给不同请求配置差异化的连接超时。

核心实现逻辑 #

WebClient本身没有暴露单请求连接超时的配置入口，但是底层Reactor Netty支持在连接建立前动态修改连接参数，我们只需要在全局初始化WebClient时预埋动态取值逻辑，发请求时把当前请求需要的超时时间通过请求属性传入即可。

第一步：初始化全局单例WebClient #

初始化时预埋超时动态读取逻辑，未配置自定义超时的请求自动走默认兜底值：

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

// 全局单例，整个应用生命周期只初始化一次
public static final WebClient GLOBAL_WEB_CLIENT = buildWebClient();
// 自定义超时属性的常量key，避免拼写错误
public static final String REQUEST_CONNECT_TIMEOUT = "customConnectTimeout";

private static WebClient buildWebClient() {
    // 全局默认连接超时：3秒
    Duration defaultConnectTimeout = Duration.ofSeconds(3);

    HttpClient httpClient = HttpClient.create()
            .observe((connection, state) -> {
                // 连接发起前的节点，此时修改连接参数可生效
                if (state == ConnectionObserver.State.CONNECTING) {
                    // 从当前请求上下文读取自定义超时配置
                    Duration timeout = connection.currentContext()
                            .getOrEmpty(REQUEST_CONNECT_TIMEOUT)
                            .map(val -> (Duration) val)
                            .orElse(defaultConnectTimeout);
                    // 给当前连接单独设置连接超时
                    connection.channel().config()
                            .setOption(ChannelOption.CONNECT_TIMEOUT_MILLIS, (int) timeout.toMillis());
                }
            })
            // 其他全局配置（比如全局响应超时、路由配置、SSL配置等）照常设置，不受影响
            .responseTimeout(Duration.ofSeconds(10));

    return WebClient.builder()
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .build();
}

第二步：发请求时按需传入自定义连接超时 #

不同请求只需要通过attributes方法传入对应超时值即可，不需要新建WebClient实例：

// 调用A服务：配置5秒连接超时
String serviceAResp = GLOBAL_WEB_CLIENT.get()
        .uri("https://service-a.example.com/query")
        .attributes(attrs -> attrs.put(REQUEST_CONNECT_TIMEOUT, Duration.ofSeconds(5)))
        .retrieve()
        .bodyToMono(String.class)
        .block();

// 调用B服务：配置1秒短连接超时，适配高可用场景快速失败
String serviceBResp = GLOBAL_WEB_CLIENT.get()
        .uri("https://service-b.example.com/ping")
        .attributes(attrs -> attrs.put(REQUEST_CONNECT_TIMEOUT, Duration.ofSeconds(1)))
        .retrieve()
        .bodyToMono(String.class)
        .block();

// 调用普通服务：不传自定义超时，自动使用全局默认的3秒连接超时
String defaultResp = GLOBAL_WEB_CLIENT.get()
        .uri("https://default.example.com/list")
        .retrieve()
        .bodyToMono(String.class)
        .block();

注意事项 #

• 该方案仅控制TCP三次握手阶段的连接超时，和读写超时、响应超时配置互不冲突，可叠加使用
• 不要用Mono.timeout()或者WebClient自带的请求级responseTimeout替代连接超时配置：前者控制的是从订阅到拿到响应的总时长，在连接阻塞阶段不会触发计时，完全覆盖不到连接建立阶段的超时场景；后者是等请求发出去之后等响应的超时，同样管不到连接阶段
• 依赖版本要求：Reactor Netty版本 >= 1.0.12，对应Spring Boot 2.7.x及以上版本均可直接使用，低版本存在上下文透传失败拿不到请求属性的问题

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