Reactor Netty WebClient未发起API调用即超时问题排查

你遇到的核心问题是：下游服务p99仅20ms，但WebClient设置2000ms超时后仍频繁触发ReadTimeoutException（嵌套在WebClientRequestException中），结合高吞吐量、单请求多下游调用的场景，可从以下方向排查修复：

1. 移除重复超时配置，明确超时职责 #

你的代码同时配置了Reactor Netty的responseTimeout和Netty原生的ReadTimeoutHandler，两者机制易冲突：

• responseTimeout：Reactor层面的全链路响应超时，限制从请求发出到完整接收响应的总时长
• ReadTimeoutHandler：Netty层面的读空闲超时，指连接建立后，连续多久没收到下游字节数据就触发超时

高并发下的网络波动或EventLoop线程排队，可能导致读空闲超时提前触发，而非总超时生效。

修复代码：
保留Reactor的全链路超时，移除Netty读空闲超时处理器：

HttpClient httpClient = HttpClient.create(provider)
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2000)
        .responseTimeout(Duration.ofMillis(responseTimeOut))
        .runOn(eventLoopGroup)
        .doOnConnected(conn ->
                // 仅保留写超时处理器
                conn.addHandlerLast(new WriteTimeoutHandler(5000, TimeUnit.MILLISECONDS)));

2. 优化连接池与EventLoop线程配置 #

（1）EventLoop线程数不足 #

你设置NioEventLoopGroup(4)，但高吞吐量下4个IO线程可能无法承载大量并发下游请求，导致IO操作排队触发超时。Netty推荐IO密集型场景的线程数为CPU核心数×2。

修复代码：
根据服务器CPU核心数动态设置线程数，且全局复用EventLoopGroup（避免每次创建WebClient都新建线程池）：

// 动态设置线程数为CPU核心数×2
EventLoopGroup eventLoopGroup = new NioEventLoopGroup(Runtime.getRuntime().availableProcessors() * 2);

（2）连接池参数适配高并发 #

当前maxConnections=1000，但单请求触发n次下游调用，高并发下易出现连接池耗尽，请求等待获取连接的时间过长（pendingAcquireTimeout=60s），后续拿到连接后剩余超时时间不足导致报错。

修复代码：

ConnectionProvider provider = ConnectionProvider.builder("fixed")
        .maxConnections(3000) // 根据「并发请求数×单请求下游调用数」估算调整
        .maxIdleTime(Duration.ofSeconds(60)) // 延长空闲时间，减少连接重建开销
        .maxLifeTime(Duration.ofMinutes(5))
        .pendingAcquireTimeout(Duration.ofMillis(500)) // 缩短等待时间，快速失败避免排队
        .evictInBackground(Duration.ofSeconds(60))
        .metrics(true)
        .build();

3. 排查下游服务长尾请求 #

虽然下游p99为20ms，但p99.9/p99.99的长尾请求可能远超2000ms，高吞吐量下这类请求的数量会被放大，导致大量超时。可通过APM工具查看下游服务的完整延迟分布确认。

4. 利用metrics监控验证配置 #

你已开启连接池metrics，可结合监控工具查看以下指标：

• reactor.netty.connection.provider.fixed.acquired：已获取的连接数
• reactor.netty.connection.provider.fixed.pending：等待获取连接的请求数
• reactor.netty.http.client.requests：请求总数、超时数等
  通过指标可直观判断连接池是否耗尽、请求是否排队，验证配置合理性。

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