如何正确配置Spring 5 WebClient的请求超时时间

我完全懂你遇到的困扰——按常规方案配置WebClient超时后，明明请求已经成功拿到响应，超时计时器却还在后台悄悄运行，既浪费资源又可能埋下潜在问题。下面给你两种精准解决的方案：

一、请求级别的超时配置（推荐，灵活无残留） #

这种方式把超时逻辑绑定到单个请求的生命周期里，请求一旦完成（不管成功还是失败），计时器会自动取消，从根源避免残留问题：

WebClient webClient = WebClient.create();

webClient.get()
        .uri("https://your-target-api.com/endpoint")
        .retrieve()
        .bodyToMono(YourResponseClass.class)
        // 绑定到当前请求的超时，响应完成后自动终止计时器
        .timeout(Duration.ofSeconds(10))
        .subscribe(
            response -> { /* 处理成功响应 */ },
            error -> { /* 处理超时或其他异常 */ }
        );

这里的timeout()是Reactor框架提供的操作符，它会严格跟着当前请求的流生命周期走，请求结束就自动清理超时计时器，不会有后台残留。

二、全局默认超时配置（正确姿势） #

如果想给所有请求设置默认超时，同时避免计时器残留，得正确配置底层的HttpClient，把超时绑定到连接和读写操作上：

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

// 配置HttpClient，设置连接、读、写超时
HttpClient httpClient = HttpClient.create()
        .tcpConfiguration(tcpClient -> tcpClient
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) // 连接超时5秒
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(10)) // 响应读取超时10秒
                        .addHandlerLast(new WriteTimeoutHandler(10)) // 请求写入超时10秒
                )
        );

// 创建WebClient时绑定配置好的HttpClient
WebClient webClient = WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();

这种配置下，超时逻辑是依附于每个请求的连接会话的，请求完成后连接会被释放，对应的超时处理器也会被移除，不会出现计时器持续运行的情况。

为什么之前的配置会出问题？ #

你之前的方案大概率是错误地在WebClient全局层面设置了独立于请求生命周期的计时器，或者用了不绑定请求流的超时方式，导致请求结束后计时器没被正确取消。而上面两种方式都是把超时逻辑和请求/连接的生命周期绑定，自然不会有残留问题。

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