Java HttpClient 异步请求超时后怎么取消 CompletableFuture

平时用JDK 11以上版本自带的HttpClient发异步请求的时候，经常碰到设置了超时但超时触发之后，关联的CompletableFuture还不会自动销毁，一直占用后台线程的问题，我们可以直接通过原生API组合的方式完成超时后的取消逻辑。

调用 Java HttpClient 的 sendAsync 后，如果只是让链式 future 以超时异常结束，并不等于底层 HTTP 交换已经被业务取消。更稳妥的做法是：用 HttpRequest.timeout 设置请求自身的截止时间，同时保留 sendAsync 返回的原始 CompletableFuture；当页面关闭、任务撤销或业务预算耗尽时，对这个原始 future 调用 cancel(true)。

先分清请求超时与业务主动取消

HttpRequest.Builder.timeout(Duration) 约束的是“多久还没有收到响应”。时间到达后，sendAsync 返回的 future 会以 HttpTimeoutException 异常完成。它适合表达网络请求的硬截止时间。

而 CompletableFuture.cancel(true) 表达的是调用方不再等待这个结果。JDK 默认 HttpClient 返回的 future 支持取消，并会尽力取消 HTTP 交换、尽快释放底层资源，但请求可能已经发出，服务端也可能已经开始处理。HTTP/1.1 可能关闭连接，HTTP/2 可能重置流，所以客户端取消不能当成服务端事务回滚。

保留原始 CompletableFuture 才能取消 HTTP 交换

下面的写法同时保留请求 future 和定时任务。请求自身有 5 秒超时；业务侧再用 3 秒预算主动取消，适合“调用方只愿意等 3 秒，但网络请求最多允许 5 秒”的场景。若请求提前完成，定时任务会被取消，避免无意义地触碰已完成的 future。

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.example.com/profile"))
        // 请求自身的最长等待时间，超时后异步 future 以 HttpTimeoutException 失败
        .timeout(Duration.ofSeconds(5))
        .GET()
        .build();

CompletableFuture> requestFuture =
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString());
ScheduledExecutorService timer = Executors.newSingleThreadScheduledExecutor();
ScheduledFuture> cancelTask = timer.schedule(() -> {
    // 只取消仍未结束的原始请求 future
    if (!requestFuture.isDone()) {
        boolean cancelled = requestFuture.cancel(true);
        System.err.println("request cancelled: " + cancelled);
    }
}, 3, TimeUnit.SECONDS);

requestFuture.whenComplete((response, error) -> {
    // 无论成功、超时还是取消，都不再需要这个定时任务
    cancelTask.cancel(false);
    try {
        if (error != null) {
            Throwable cause = error instanceof CompletionException
                    ? error.getCause() : error;
            if (cause instanceof CancellationException) {
                System.out.println("业务主动放弃请求");
            } else {
                System.err.println("HTTP 请求失败: " + cause);
            }
            return;
        }
        System.out.println(response.statusCode());
        System.out.println(response.body());
    } finally {
        // 定时器是本例创建的资源，回调结束后关闭它
        timer.shutdown();
    }
});

关键是不要只保存 thenApply(HttpResponse::body) 返回的下游阶段。下游阶段适合转换结果，原始 future 才是 HttpClient 返回的可取消对象。需要把取消动作暴露给控制器时，可以把 requestFuture 包装成任务句柄，但不要丢掉它。

按异常类型收口超时、取消和网络错误

回调里的 error 可能被 CompletionException 包装，先取出根因再判断。主动取消是正常控制流，不应和 DNS 失败、连接失败混进同一个“系统错误”指标。

static Throwable rootCause(Throwable error) {
    // 链式阶段常用 CompletionException 包装原始异常
    if (error instanceof CompletionException && error.getCause() != null) {
        return error.getCause();
    }
    return error;
}

requestFuture.whenComplete((response, error) -> {
    if (error == null) {
        // 只有这里才读取成功响应
        handleSuccess(response.statusCode(), response.body());
        return;
    }
    Throwable cause = rootCause(error);
    if (cause instanceof CancellationException) {
        recordCancelled();
    } else if (cause instanceof java.net.http.HttpTimeoutException) {
        recordTimeout();
    } else {
        recordNetworkFailure(cause);
    }
});

如果使用 orTimeout 只改变 future 的完成结果，它更像“调用方不再等待”的信号；需要尽力停止 HttpClient 交换时，仍应保留并取消原始 future。重试也要放在明确的错误分类之后，主动取消通常不应自动重试。

检查响应体与连接资源的边界

BodyHandlers.ofString() 会把响应体收集成字符串，适合体积可控的接口。大响应或流式处理应使用相应的 body subscriber，并确保最终读到结束、关闭流或取消订阅。仅仅让 CompletableFuture 结束，并不能替代响应体资源的收尾。

排查“取消后连接数仍不降”时，按这张清单看：是否取消了原始 future；是否已经进入服务端处理阶段；是否选择了流式 BodyHandler 却没有读完或关闭；是否把主动取消错误记成了网络故障。这样能把客户端状态、协议流状态和服务端业务状态分开。

常见追问

调用 cancel(false) 可以吗？可以触发 CompletableFuture 的取消状态，但对 HttpClient 来说，文档明确的取消入口是对可取消 future 调用 cancel(true)。参数不保证中断远端执行，关键仍是操作正确的原始 future。

取消后服务端一定收不到请求吗？不一定。取消可能发生在请求已发送或服务端已开始处理之后；如果业务有写入、扣款等副作用，必须依靠服务端幂等键、状态查询或补偿机制解决。