Java HttpClient 怎样分别限制连接建立与响应等待

如果一个 Java HTTP 请求“连不上”和“连上后一直等”都只配置一个总超时，排查时很容易把两类问题混在一起。更清晰的做法是：在 HttpClient 上设置 connectTimeout，限制需要新建连接时的建立时间；在具体 HttpRequest 上设置 timeout，限制等待响应的时间。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpClient.html

一句话记忆：connectTimeout 管“新连接能不能及时建立”，HttpRequest.timeout 管“这个请求能不能及时收到响应”。前者是客户端级配置，后者是请求级配置。

我在处理外部 HTTP 依赖时，先把这两个时间拆开，再看异常类型和连接是否复用。这样即使没有额外的网络监控，也能先得到一个足够可靠的故障分类。

先分清客户端级与请求级边界

HttpClient.Builder.connectTimeout(Duration) 只描述连接建立阶段，而且只有本次请求需要建立新连接时才有作用；如果连接池里已有可复用连接，它不会因为连接复用而重新计时。HttpRequest.Builder.timeout(Duration) 则绑定一条请求，响应没有在指定时间内收到时，send 抛出 HttpTimeoutException，异步调用会以该异常结束。

因此，不要把“连接超时”理解成整个请求的总时长，也不要把请求级超时误写成客户端的全局默认值。一个客户端可以复用，但每条请求仍然可以根据接口特点选择不同等待上限。

配置连接建立超时：只给新连接设上限

下面的例子把客户端连接建立上限设为 3 秒，再为同一条请求设置 8 秒的响应等待上限。代码里的数字只是演示配置，生产环境应按目标服务、代理链路和业务容忍度调整。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class TimeoutSplitExample {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newBuilder()
                // 只限制需要新建连接时的建立时间。
                .connectTimeout(Duration.ofSeconds(3))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/health"))
                // 限制这条请求等待响应的时间。
                .timeout(Duration.ofSeconds(8))
                .GET()
                .build();

        try {
            HttpResponse response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            // 收到响应后再读取状态码，便于区分 HTTP 失败和超时异常。
            System.out.println(response.statusCode());
        } catch (java.net.http.HttpConnectTimeoutException e) {
            // 新连接在 3 秒内没有建立成功。
            System.err.println("连接建立超时：" + e.getMessage());
        } catch (java.net.http.HttpTimeoutException e) {
            // 请求在 8 秒内没有收到响应。
            System.err.println("响应等待超时：" + e.getMessage());
        } catch (java.io.IOException e) {
            // 其他网络 I/O 错误单独记录，避免统称为超时。
            System.err.println("HTTP I/O 失败：" + e.getMessage());
        } catch (InterruptedException e) {
            // 恢复中断标记，让上层线程仍能感知取消信号。
            Thread.currentThread().interrupt();
        }
    }
}

这里先捕获 HttpConnectTimeoutException，再捕获它的父类 HttpTimeoutException，否则父类分支会提前接住连接超时。Duration 必须是正数；不设置请求超时时，官方语义等价于无限等待，网络依赖不应默认依赖这个行为。

为不同请求设置不同的响应等待时间

客户端级连接策略可以共享，但请求级响应策略通常不应“一刀切”。例如健康检查希望快速失败，报表接口可能允许更长的服务端计算时间。两条请求使用同一个客户端时，只需在各自的 Builder 上设置不同的 timeout。

HttpRequest quickCheck = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/health"))
        // 健康检查只等待较短时间，避免占满调用线程。
        .timeout(Duration.ofSeconds(2))
        .GET()
        .build();

HttpRequest report = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/report"))
        // 报表接口允许更长的服务端处理时间。
        .timeout(Duration.ofSeconds(20))
        .GET()
        .build();

这两个请求都可以交给同一个 HttpClient 发送；连接建立超时仍由客户端配置决定，而响应等待上限由当前请求决定。若使用 sendAsync，超时不会变成返回值，而是让返回的 CompletableFuture 以 HttpTimeoutException 异常完成。

用连接复用和异常类型解释结果

排查时我会先问两个问题：本次是否需要新建连接？异常到底是哪一个类型？官方文档明确指出，连接复用时 connectTimeout 对这次请求没有作用；因此，复用连接上的慢响应通常应从请求级 timeout 和服务端处理时间解释，而不是继续调大连接超时。

这里的“通常”很重要：异常归因仍要结合代理、DNS、TLS 和连接池日志。两个超时值不是性能指标本身，不能仅凭它们推断服务端一定慢；它们首先是客户端的失败边界。

常见问题

只设置 connectTimeout，能限制整个请求吗？

不能。它只在需要建立新连接时限制连接建立时间；响应等待仍应使用请求级 timeout。

请求 timeout 不设置会怎样？

官方文档把未设置请求超时的语义定义为无限等待。对外部依赖，建议显式设置正的 Duration，并在上层记录超时类型。

为什么复用连接时没有触发 connectTimeout？

因为这次没有新的连接建立动作。连接复用属于 HttpClient 的连接池行为，此时应该继续看请求级等待上限和服务端响应。

总结

Java HttpClient 的两个超时入口分别解决两个阶段：客户端的 connectTimeout 负责新连接建立，请求的 timeout 负责响应等待。把作用域、连接复用和异常类型一起记录，才能在有限日志下快速区分“连不上”和“等不到响应”。