Java HttpClient读取响应体超时并取消异步请求的方法

Java HttpClient 的 connectTimeout 只负责建立连接，不能替代“响应体必须在几秒内读完”的业务截止时间。要处理响应体超时，可以让 sendAsync 返回的 future 保存为 exchange，再用一个定时任务调用 exchange.cancel(true)；在 whenComplete 里取消定时任务并关闭调度器。

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

先区分连接超时和响应体超时

一个接口可能很快完成 TCP/TLS 建连，却在发送响应体时持续等待。此时 HttpClient.newBuilder().connectTimeout(...) 已经完成使命，future 仍然没有结果。Oracle API 对 sendAsync 的定义是返回 CompletableFuture>；当使用 BodyHandlers.ofString() 时，正文读取也属于这次异步交换的一部分。

用定时任务取消未完成的响应体读取

下面的写法把取消对象命名为 exchange，避免把“超时任务”和“HTTP 请求”混成一个变量。示例只展示请求治理结构，不依赖某个真实接口的运行结果。

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.CancellationException;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;

HttpClient client = HttpClient.newBuilder()
    // 建连超时不覆盖响应体读取阶段
    .connectTimeout(Duration.ofSeconds(2))
    .build();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.example.com/report"))
    // 给请求本身设置可复制的业务超时语义
    .timeout(Duration.ofSeconds(10))
    .GET()
    .build();
ScheduledExecutorService timer = Executors.newSingleThreadScheduledExecutor();
CompletableFuture> exchange =
    client.sendAsync(request, HttpResponse.BodyHandlers.ofString());
ScheduledFuture> timeoutTask = timer.schedule(() -> {
    // 取消的是原始 HTTP future，释放动作由 HttpClient 尽力完成
    exchange.cancel(true);
}, 5, TimeUnit.SECONDS);

exchange.whenComplete((response, error) -> {
    // 完成、异常或取消都要停止定时任务并收束调度线程
    timeoutTask.cancel(false);
    timer.shutdown();
    if (error instanceof CancellationException) {
        System.out.println("请求超过截止时间或被主动取消");
    } else if (error != null) {
        Throwable cause = error instanceof CompletionException && error.getCause() != null
            ? error.getCause() : error;
        System.err.println("HTTP 异步请求失败：" + cause.getClass().getSimpleName());
    } else {
        System.out.println("状态码：" + response.statusCode());
        System.out.println("响应体长度：" + response.body().length());
    }
});

这里的 HttpRequest.timeout 是请求级超时信号，具体实现仍应把最终截止策略落到可观察的 future 上。定时器触发后，cancel(true) 可能让 HTTP/1.1 连接关闭或让 HTTP/2 流重置，但底层释放不会同步完成。

在完成回调里收束异常和资源

whenComplete 不等于成功回调：响应成功、网络 I/O 异常、主动取消都可能进入这里。不要把 CancellationException 当成服务端 500，也不要在每个分支重复创建新的调度器。超时任务只负责发起取消，清理动作集中在完成回调中更容易审查。

如果业务还要重试，先给每次尝试分配独立的请求标识，再决定是否允许重试。取消旧 future 后立即发送新请求，不能证明服务端已经停止处理；高并发场景还要结合连接池、上游幂等性和重试预算一起设限。

常见问题

只设置 connectTimeout 能解决响应体卡住吗？

不能。它主要限制建立连接，响应体读取仍需单独的业务截止时间。

orTimeout 和 cancel(true) 应该怎么选？

orTimeout 适合先让 future 以超时异常结束；需要明确尝试收束 HTTP 交换时，应保留原始 future 并调用 cancel(true)。

cancel(true) 是否保证服务器停止执行？

不保证。它是客户端侧的取消尝试，服务端是否停止还取决于协议、服务器实现和请求是否已经开始处理。