Java HttpClient 怎么复用客户端并设置请求超时

Java HttpClient 的正确用法通常不是“每个请求 new 一个客户端”，而是让服务生命周期内复用同一个已构建的客户端，再给每个请求设置自己的等待预算。连接建立超时和请求总超时也要分开看：前者只约束新连接，后者约束响应迟迟没有完成的单次请求。

把 HttpClient 作为共享的不可变依赖，使用 connectTimeout 控制建立连接的时间，再用 HttpRequest.Builder.timeout 控制单次请求；捕获不同异常，才能知道慢在连接、响应还是业务处理。

故障现象：每次调用都新建客户端，超时还看不懂

一次批量同步任务出现了两个同时变化的指标：远端服务没有明显扩容，但本地连接创建次数增加，接口 P95 也开始抖动。排查调用代码时，问题常常藏在一个很小的工厂方法里：方法每次执行都重新构造 HttpClient，然后马上发送一个请求。

HttpClient 构建后是不可变对象，可以发送多个请求；JDK 实现通常为实例维护自己的连接池。每次操作都创建新实例，会让连接复用失去意义。适合的边界是把客户端放在一个长生命周期服务中，把请求对象留在具体调用方法里：

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

final class RemoteGateway {
    // 客户端只构建一次，服务对象生命周期内重复使用
    private final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(3))
            .build();

    String load(String endpoint) throws Exception {
        // 请求可以按接口特点单独设置响应等待预算
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(endpoint))
                .timeout(Duration.ofSeconds(8))
                .GET()
                .build();
        return client.send(request, HttpResponse.BodyHandlers.ofString()).body();
    }
}

这里共享的是已经 build 的客户端，不是 Builder。Builder 会被 setter 修改，不能在多个线程之间当作共享配置对象；HttpRequest 构建后则是不可变的，可以在需要时保存或重复发送。

根因一：连接超时和请求超时管的不是一件事

connectTimeout 配在 HttpClient.Builder 上，含义是“需要建立新连接时，最多允许多久”。如果连接已经从客户端维护的资源中复用，这个连接超时不会重新计时。它适合发现地址不可达、握手迟迟无法完成等问题。

timeout 配在 HttpRequest.Builder 上，含义是“这一次请求在规定时间内没有收到响应就结束”。不设置请求 timeout 的效果相当于无限等待，后台任务因此可能长期占住线程或异步链路。两个时间都必须是正数，生产配置应按接口等级设定，而不是把所有接口硬编码成一个值。

可以用下面的表格做快速判断：

根因二：异常被抹平，日志只剩一句请求失败

同步调用会直接抛出异常；异步调用则通常以 exceptionally 的形式完成。不要把所有异常都包装成同一个 RuntimeException，否则连接建立失败和远端响应过慢会落到同一条告警里。记录请求 URI、阶段、耗时和异常类型即可，不要把 Authorization 等敏感请求头写入日志。

import java.io.IOException;
import java.net.http.HttpConnectTimeoutException;
import java.net.http.HttpTimeoutException;

try {
    HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
    // 收到响应后再判断协议状态，不把 5xx 当成网络超时
    if (response.statusCode() >= 400) {
        throw new IllegalStateException("remote status=" + response.statusCode());
    }
    return response.body();
} catch (HttpConnectTimeoutException ex) {
    // 新连接没有在预算内建立
    throw new IllegalStateException("connect timeout", ex);
} catch (HttpTimeoutException ex) {
    // 请求没有在预算内收到响应
    throw new IllegalStateException("request timeout", ex);
} catch (IOException ex) {
    // 其他网络或响应读取错误
    throw new IllegalStateException("http io failure", ex);
} catch (InterruptedException ex) {
    // 保留中断标记，交给上层决定是否取消任务
    Thread.currentThread().interrupt();
    throw new IllegalStateException("request interrupted", ex);
}

如果使用 BodyHandlers.ofInputStream() 等流式处理方式，必须消费或关闭返回的流；否则即使客户端复用正确，也可能让资源迟迟不能释放。应用停机时再按生命周期调用客户端的关闭方法，短请求不需要每次都关闭共享客户端。

落地检查：用一组日志确认复用和超时策略

上线前先检查四件事：客户端是否只在服务初始化阶段构建；每类请求是否有明确的 timeout；连接异常与请求异常是否分开统计；响应流是否有消费和关闭路径。压测时同时观察连接创建数、请求耗时分位数、超时异常类型和远端状态码，单看平均耗时很容易漏掉连接建立抖动。

若大量请求命中 HttpConnectTimeoutException，先查网络路径和代理，不要盲目增加请求 timeout；若连接正常但 HttpTimeoutException 增多，再看服务端处理时间、响应体大小和接口预算。收到 4xx/5xx 则说明 HTTP 响应已经返回，应该进入协议或业务重试策略。

相关问题

HttpClient 可以做成单例吗？

可以把已构建的 HttpClient 放到应用或服务生命周期中复用，但不要共享一个会不断修改的 Builder。

connectTimeout 能限制整个请求耗时吗？

不能。它主要约束新连接建立；整个请求的等待预算应通过 HttpRequest.Builder.timeout 设置。

请求超时后还会继续占用连接吗？

取消和资源释放由实现异步完成，不能把异常抛出瞬间当作所有底层资源已释放；流式响应尤其要保证消费或关闭。