Java HttpClient 分层超时的配置方法

我在给一个外部接口加超时时，最容易踩的坑不是 Duration 写错，而是把“建立连接”和“等待一次请求完成”当成了同一个计时器。Java 11 引入的 java.net.http.HttpClient 正好把这两个边界拆开：客户端用 connectTimeout 限制新连接建立，请求用 timeout 限制一次请求交换。这样配置后，慢 DNS、连接失败、服务端迟迟不返回和响应体过慢不会再被混成一个模糊的“请求超时”。

官方文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.net.http/java/net/http/HttpClient.html

先把两个超时的职责分开

连接超时属于客户端配置。它覆盖从请求需要连接开始，到 TCP 连接建立完成的阶段；官方实现还建议把 SSL/TLS 握手纳入这个阶段。因此它适合限制“目标地址暂时连不上”，而不是限制服务端处理业务的时间。

请求超时属于单个 HttpRequest。它从请求执行开始计时，至少覆盖到 HttpResponse 构造完成；JDK 内置实现会继续计时到响应体订阅者完成。也就是说，不能把它理解成只等待响应头的 socket 读超时。

HttpClient 的超时参数如何组合

实战中可以把客户端做成可复用对象，把请求总时限留给每个调用方。下面的示例把连接上限设为 2 秒、单次请求上限设为 5 秒，重点是参数的归属和异常边界：

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpConnectTimeoutException;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpTimeoutException;
import java.time.Duration;

public final class TimeoutClient {
    private final HttpClient client = HttpClient.newBuilder()
            // 只限制新建 TCP/TLS 连接的阶段，连接复用时不重新计算。
            .connectTimeout(Duration.ofSeconds(2))
            .build();

    public String get(String url) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
                // 限制本次请求交换，包含响应体消费的 JDK 实现路径。
                .timeout(Duration.ofSeconds(5))
                .GET()
                .build();

        try {
            HttpResponse response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            // 超时配置不等于业务成功，仍要检查 HTTP 状态码。
            if (response.statusCode() >= 400) {
                throw new IOException("remote status: " + response.statusCode());
            }
            return response.body();
        } catch (HttpConnectTimeoutException ex) {
            // 连接阶段失败，重试前应先检查地址、代理和网络路径。
            throw new IOException("connect timeout", ex);
        } catch (HttpTimeoutException ex) {
            // 请求整体超时，是否重试要看方法幂等性和服务端副作用。
            throw new IOException("request timeout", ex);
        }
    }
}

两个 Duration 都必须是正数；不设置请求超时等价于无限等待。对于 POST 等可能产生副作用的调用，捕获超时后不要直接重试，先确认接口是否支持幂等键。

调用方怎样区分异常并保留边界

异常类型比异常消息更适合做路由。HttpConnectTimeoutException 是连接建立阶段的特化异常，HttpTimeoutException 表示请求级超时。异步调用时，它们通常会作为 CompletableFuture 的异常完成原因出现，调用方要在统一的错误处理层解包后再分类。

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.CompletionException;

static void sendAsync(HttpClient client, HttpRequest request) {
    client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
            .whenComplete((response, error) -> {
                if (error == null) {
                    // 只把 2xx/3xx 等业务允许的状态交给后续处理。
                    System.out.println(response.statusCode());
                    return;
                }
                Throwable cause = error instanceof CompletionException
                        ? error.getCause() : error;
                // 统一记录分类，避免把连接失败和服务端慢响应混为一谈。
                if (cause instanceof java.net.http.HttpConnectTimeoutException) {
                    record("connect-timeout", cause);
                } else if (cause instanceof java.net.http.HttpTimeoutException) {
                    record("request-timeout", cause);
                } else {
                    record("transport-error", cause);
                }
            });
}

static void record(String kind, Throwable error) {
    // 生产实现应带上请求标识，但不要把完整 Authorization 写入日志。
    System.err.println(kind + ": " + error.getClass().getSimpleName());
}

这套配置适合哪些请求

短请求、查询接口、明确有 SLA 的内部调用，适合采用“共享 HttpClient + 请求级 timeout”的组合。连接超时应略小于整体请求时限，给 DNS、连接池和业务处理留下可解释的余量，但不要把两个数字机械地固定成同一个值。

需要持续下载、长轮询或流式响应时，要重新定义“完成”：请求超时可能覆盖到响应体消费完成，不能拿它替代按字节或按空闲时间设计的流控。Java HttpClient 本身也没有一个名为 readTimeout 的独立 Builder 参数；如果业务需要空闲读超时，应在响应体处理层实现可取消的消费策略。

常见问题

只设置 connectTimeout，为什么请求仍然会一直等？

它只负责新连接建立。连接成功后，服务端迟迟不返回或响应体持续很慢，仍需要在 HttpRequest 上设置 timeout。

请求复用连接时 connectTimeout 还会重新倒计时吗？

不会。官方说明中，连接复用时不需要建立新连接，因此连接超时对该次复用没有作用；请求级 timeout 仍然独立生效。

捕获 HttpTimeoutException 后能不能直接重试？

不能一概而论。GET 等幂等请求可以在退避和次数限制下评估重试；POST 需要先确认幂等语义，否则可能造成重复写入。