Java HttpClient设置请求超时并读取异步异常的实现方法

Java 11 的 HttpClient 异步请求，建议把超时写在 HttpRequest 上，把结果和异常交给 CompletableFuture.handle 统一处理。这样既能限制一次请求从开始到响应体消费的等待时间，也能在同一个分支里区分 HTTP 状态码、HttpTimeoutException 和其他网络异常。

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

一、先确定生产目标：复用客户端，限制单次请求

这个场景只讨论 CompletableFuture 的结果处理，不把连接池调优、代理认证或响应流式下载混在一起。客户端负责发送请求，请求对象负责声明本次调用的超时，future 负责把异步结果交给后续代码。HttpClient 是不可变对象，可以服务多个请求；每次 new 一个客户端会削弱连接复用。

二、环境准备：把 timeout 写在请求上

下面的最小模板使用 BodyHandlers.ofString()，让 future 在响应体读完后携带完整字符串。timeout 必须是正的 Duration；没有设置请求超时时，效果相当于无限等待。

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

HttpClient client = HttpClient.newBuilder()
    // 客户端可复用；连接建立超时与单次请求超时是两层边界
    .connectTimeout(Duration.ofSeconds(3))
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/profile"))
    // 限制本次请求从执行开始到响应体处理完成的等待
    .timeout(Duration.ofSeconds(5))
    .header("Accept", "application/json")
    .GET()
    .build();

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

这里的 connectTimeout 只针对客户端建立连接的阶段，而请求级 timeout 是本次交换的总边界。实际项目中不要只凭一个数字判断慢请求，应把两者分别记录在配置和日志里。

三、安全配置与异常读取：用 handle 保留根因

handle 无论 future 正常还是异常都会执行：正常时第二个参数为 null，异常时第一个参数通常为 null。它适合把响应状态和异常归一成一个结果对象，避免在多个回调里重复写日志。

record CallResult(int status, String body, String errorType, String message) {}

CompletableFuture result = future.handle((response, error) -> {
    // error 表示异步阶段失败；失败时不要读取 response.statusCode()
    if (error != null) {
        Throwable cause = error;
        // handle 通常拿到原始异常；兼容包装异常时继续向下找根因
        while (cause.getCause() != null
                && (cause instanceof java.util.concurrent.CompletionException
                    || cause instanceof java.util.concurrent.ExecutionException)) {
            cause = cause.getCause();
        }
        return new CallResult(0, "", cause.getClass().getSimpleName(), cause.getMessage());
    }
    // HTTP 500 仍是正常收到的响应，不能当成网络异常
    return new CallResult(response.statusCode(), response.body(), "", "");
});

result.thenAccept(value -> {
    // status=0 表示没有拿到 HTTP 响应；非 2xx 则是服务端业务边界
    System.out.printf("status=%d error=%s message=%s%n",
        value.status(), value.errorType(), value.message());
});

超时会落到异常分支，常见类型是 HttpTimeoutException；DNS、连接拒绝和 TLS 失败也会落在同一类 future 异常处理中。相反，服务器返回 404 或 500 时，future 仍可能正常完成，必须先读 statusCode() 再决定是否重试。

四、权限边界与发布检查：别让 join 隐藏超时

如果上层接口必须同步拿到结果，可以调用 join()，但它会把失败包装成 CompletionException。日志和监控应继续检查 getCause()，否则告警里只剩一个泛化异常名。

try {
    // join 不再增加网络超时，只等待前面已经定义的 future 结果
    CallResult value = result.join();
    if (value.status() = 300) {
        // 非 2xx 是收到响应后的业务判断，按接口契约决定是否重试
        throw new IllegalStateException("unexpected http status=" + value.status());
    }
} catch (java.util.concurrent.CompletionException ex) {
    // 发布前检查日志必须保留 cause，才能识别超时、连接失败或解析失败
    Throwable root = ex.getCause() == null ? ex : ex.getCause();
    System.err.println(root.getClass().getSimpleName() + ": " + root.getMessage());
}

上线前至少检查四项：请求是否复用了同一个 HttpClient、timeout 是否大于零、异常日志是否保留根因、非 2xx 是否没有被误记成网络超时。若链路还需要统一兜底，可在 handle 之后再接 thenApply 或 exceptionally，不要同时对同一个 future 发起多套重试。

常见问题

HttpClient 的 connectTimeout 能代替 request timeout 吗？

不能。前者主要约束建立连接，后者约束这次请求交换的等待范围；接口响应慢时仍需要 request timeout。

收到 500 时为什么没有进入异常回调？

500 是已经收到的 HTTP 响应，通常属于正常完成的 future。先检查状态码，再按业务规则决定降级或重试。

handle 和 exceptionally 应该怎么选？

需要同时观察成功值和异常时选 handle；只想在失败时提供兜底值且保留成功结果时，exceptionally 更直接。

把超时、HTTP 状态和异步异常拆成三种信号后，Java HttpClient 的排查路径会稳定很多：先确认有没有响应，再确认响应是否可接受，最后从异常根因判断网络或超时。