Spring WebFlux发起POST请求时出现flatMap超时异常的问题咨询

我目前在用Spring WebFlux发起POST请求，但是遇到了下面的超时异常：

java.util.concurrent.TimeoutException:

Did not observe any item or terminal signal within 20000ms in 'flatMap'

(and no fallback has been configured)

我的代码如下：

public Mono<ResponseEntity<XXXResponse>> invokeXXXService(XXXRequest request) {

        return webClient
                .baseUrl(XXXUrl)
                .build()
                .post()
                .contentType(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(request))
                .exchangeToMono(clientResponse -> clientResponse.toEntity(XXXResponse.class))
                .timeout(java.time.Duration.ofMillis(20000))
                .onErrorResume(throwable -> {
                    LOG.error("Errors while getting res from XXX");
                    return Mono.just(ResponseEntity.status(500).body(null));
                });
    }

问题分析 #

这个超时异常提示在flatMap操作里20秒内没收到任何响应或者终端信号，大概率是这几个原因导致的：

• 你设置的20秒超时可能不够用，目标服务XXXUrl的响应速度本身就超过了这个时长
• 代码里每次调用都重新build()WebClient实例，这会重复创建资源，容易引发连接池或配置层面的隐性问题，WebClient本来就该以单例形式复用
• 目标服务可能根本没正常处理请求，比如网络不通、参数格式错误导致服务卡住无响应

解决方案建议 #

1. 复用WebClient单例实例
   别每次调用都创建新的WebClient，建议把它配置成单例Bean注入使用：

@Bean
public WebClient webClient() {
    return WebClient.builder()
            .baseUrl(XXXUrl)
            .build();
}

之后在你的方法里直接注入这个Bean，去掉原代码里的baseUrl(XXXUrl).build()部分，避免重复实例化带来的资源浪费和潜在问题。

2. 优化超时配置与异常日志
   先临时延长超时时间测试，比如改成30秒，同时在onErrorResume里打印更详细的异常栈信息，方便定位问题：

.onErrorResume(throwable -> {
    LOG.error("Errors while getting res from XXX: {}", throwable.getMessage(), throwable);
    return Mono.just(ResponseEntity.status(500).body(null));
});

这样能区分是真的超时，还是有其他异常被超时逻辑覆盖了。

3. 排查目标服务可用性
   用Postman或curl直接调用XXXUrl的POST接口，传入相同的XXXRequest参数，看看服务是否能正常返回、响应时长是多少。如果服务本身响应就慢，要么优化目标服务，要么合理调整超时时间。

4. 显式配置WebClient底层超时
   可以分开配置连接超时和响应超时，比只在Mono上设置timeout更全面：

@Bean
public WebClient webClient() {
    HttpClient httpClient = HttpClient.create()
            .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) // 连接超时5秒
            .responseTimeout(Duration.ofSeconds(20)); // 响应超时20秒
    return WebClient.builder()
            .baseUrl(XXXUrl)
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .build();
}

备注：内容来源于stack exchange，提问作者Lakshitha Samod