接口超时别只调大 timeout：Java HTTP 客户端其实有 3 段等待

接口一慢，很多人的第一反应是把 timeout 从 3 秒改成 10 秒。

这招偶尔能止血，但经常把问题藏得更深。一次 HTTP 调用里至少有三段等待：从连接池拿连接、建 TCP／TLS 连接、等下游响应。把它们混成一个「接口超时」，排障时基本只能靠猜。

卡在连接池：请求甚至还没出去

池子里的连接都被占用时，新请求要先排队。Apache HttpClient 5 里的 connectionRequestTimeout 管的就是这段「向连接管理器租连接」的时间。

日志里如果同时出现这些信号，就先别急着改下游超时：

text 复制代码

leased = max
pending > 0
下游接口耗时没有明显升高

这种情况扩容前要先看连接为什么不归还。常见的是响应体没关闭、下游慢把连接长期占住，或者每个请求都带着过长的响应等待。单纯把池调大，可能只是把排队从客户端推到下游。

卡在建连：连接复用时它根本不生效

connectTimeout 管的是新连接建立。JDK 的 HttpClient.Builder.connectTimeout 文档写得很直白：连接复用时，这个超时没有作用。

所以线上「connect timeout」偶发，不代表所有慢请求都在网络层。它更像一盏针对新建连接的灯。DNS、TCP 握手、TLS 协商，或者目标端口不可达，都可能在这里暴露。

卡在等响应：给下游留多少预算

连接已经拿到，也建好了，服务端还是可能迟迟不回。Apache HttpClient 5 的 responseTimeout 和 JDK HttpRequest.timeout 都覆盖这一段等待，不过语义不要想当然地等同于「整条链路总耗时」。

我更愿意按预算配，而不是三个参数抄同一个数字。假设网关给这个接口 3 秒，客户端可以先留出一点重试和序列化时间，再把剩下的预算拆给拿连接、建连和下游响应。

下面这组配置不是通用答案，只是把三段时间显式分开：

java 复制代码

var connectionConfig = ConnectionConfig.custom()
    .setConnectTimeout(Timeout.ofSeconds(1))
    .build();

var requestConfig = RequestConfig.custom()
    .setConnectionRequestTimeout(Timeout.ofSeconds(2))
    .setResponseTimeout(Timeout.ofSeconds(5))
    .build();

try (var manager = PoolingHttpClientConnectionManagerBuilder.create()
        .setDefaultConnectionConfig(connectionConfig)
        .build();
     var client = HttpClients.custom()
        .setConnectionManager(manager)
        .setDefaultRequestConfig(requestConfig)
        .build()) {
    // client.execute(...)
}

面试里被问「HTTP 客户端超时怎么配」，别只报一个数字。先问清请求是在排队、建连，还是等响应，再说对应的配置和监控项。

我会至少把 leased、pending、连接失败类型、下游耗时分位数放到同一张面板里。这样看到超时，才知道该扩池、查网络，还是去找下游服务。

文中 API 语义按 Apache HttpComponents Client 5.5 与 JDK 24 的官方文档核对。