Java HttpClient 异步超时 怎样处理

Java HttpClient 的异步超时要先分成两类：建立新连接的时间，和一次请求从开始到响应完成的时间。前者配置在 HttpClient，后者配置在 HttpRequest。如果只给客户端设置 connectTimeout，连接复用或服务端迟迟不返回时，请求仍可能等待很久。

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

实用做法是同时设置客户端连接超时和请求级超时，再在 CompletableFuture 的完成阶段分类处理 HttpConnectTimeoutException、HttpTimeoutException 与取消。外部 orTimeout 可以作为业务截止时间，但它不等于底层 HTTP 交换已经停止。

先分清：连接超时和请求超时不是一只表

HttpClient.Builder.connectTimeout 只在需要建立新连接时生效；连接已经从池中复用时，这个值不再约束本次请求。连接阶段超时，异步调用会以 HttpConnectTimeoutException 异常完成。

HttpRequest.Builder.timeout 是请求级超时。它从请求执行开始计时，至少覆盖到响应对象构造；JDK 内置实现还会把响应体消费完成纳入计时。未设置请求超时时，效果相当于无限等待。两者的静态关系可以这样记：

先把两只表写进代码，后续才有明确的排查口径：

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

HttpClient client = HttpClient.newBuilder()
        // 只限制建立新连接的阶段，连接复用时不重新计时
        .connectTimeout(Duration.ofMillis(500))
        .build();

HttpRequest request = HttpRequest.newBuilder(URI.create("https://example.com/data"))
        // 限制本次请求的执行与响应体处理，避免无限等待
        .timeout(Duration.ofSeconds(2))
        .GET()
        .build();

client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        // 异步调用返回 CompletableFuture，不要在这里阻塞等待
        .thenAccept(response -> System.out.println(response.statusCode()));

异步链路里，异常要在完成阶段处理

sendAsync 返回的是 CompletableFuture。连接超时和请求超时通常会被包装在 CompletionException 中，所以只判断最外层异常名称，容易把两类问题混在一起。处理器应先解包，再记录超时类别、目标主机和请求阶段。

import java.net.http.HttpConnectTimeoutException;
import java.net.http.HttpTimeoutException;
import java.util.concurrent.CompletionException;

var future = client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

future.whenComplete((response, error) -> {
    if (error == null) {
        // 只有响应正常完成时才记录状态码和响应体耗时
        recordSuccess(response.statusCode());
        return;
    }

    Throwable cause = error;
    // CompletableFuture 常用 CompletionException 包住真正原因
    if (cause instanceof CompletionException && cause.getCause() != null) {
        cause = cause.getCause();
    }

    if (cause instanceof HttpConnectTimeoutException) {
        // 连接阶段失败，优先检查 DNS、代理、网络路径或连接池状态
        recordTimeout("connect");
    } else if (cause instanceof HttpTimeoutException) {
        // 请求阶段超时，检查服务端响应、响应体大小和阈值是否合理
        recordTimeout("request");
    } else if (cause instanceof java.util.concurrent.CancellationException) {
        // 取消是调用方主动结束，不应冒充服务端超时
        recordCancelled();
    } else {
        // 其它异常保留原始类型，避免排查信息被统一成 timeout
        recordFailure(cause);
    }
});

如果业务还有比请求级超时更短的截止时间，可以在返回的 future 上使用 orTimeout。它改变的是 future 的完成结果；若业务确实要停止底层工作，应保留原始 future，在超时分支尝试调用 cancel(true)，并把“业务截止”与“HTTP 请求超时”分别计数。

用基线指标决定阈值，不要只凭感觉填秒数

超时值应从可解释的指标开始。至少分别记录连接耗时、等待响应头耗时、响应体完成耗时、超时类型和取消数量；再按接口的 p95、p99 观察长尾。下面的数字只是记录格式示例，不是本文已经执行的压测结果：

例如，若接口的正常 p99 已接近两秒，就不能简单把请求超时设成两秒后宣称“更快”；应先确认长尾来自连接、服务端处理还是响应体传输。连接超时则应根据网络环境单独设定，不要因为某个接口慢就无限放大连接等待。

常见边界：复用、响应体和重试

• 连接复用：connectTimeout 不会约束已建立连接上的服务端处理时间，慢请求仍要依靠 HttpRequest.timeout。
• 响应体读取：使用流式 BodyHandler 时，要明确谁负责关闭、取消或读完流；否则请求资源可能迟迟不释放。
• 重试：超时不代表请求一定没有到达服务端。对写请求自动重试前，必须确认幂等性和业务去重键。
• 客户端复用：尽量复用同一个 HttpClient，否则连接池复用收益和连接超时统计都会失真。

相关问题

• 为什么设置了 connectTimeout，sendAsync 还是等很久？它主要约束新连接建立；连接已复用或服务端响应慢时，要检查请求级超时。
• orTimeout 和 HttpRequest.timeout 该选哪个？前者适合业务层截止时间，后者是 HttpClient 请求边界；两者可以并存，但指标和异常要分开。

参考资料

https://docs.oracle.com/en/java/javase/26/docs/api/java.net.http/java/net/http/HttpClient.Builder.html

https://docs.oracle.com/en/java/javase/26/docs/api/java.net.http/java/net/http/HttpRequest.Builder.html

https://docs.oracle.com/en/java/javase/26/docs/api/java.net.http/java/net/http/HttpClient.html