CompletableFuture.orTimeout不能替代手动超时逻辑，因为它仅标记结果超时而不中断底层任务；HTTP调用需配合cancel(true)和响应式客户端才能真正终止请求。
CompletableFuture.orTimeout 为什么不能直接替代手动超时逻辑
Java 9 引入的 orTimeout 看起来很理想：调用一次就自动抛异常、不用自己起定时任务。但它只在「内部未完成」时触发，**不中断正在执行的异步任务本身**——也就是说，底层 HTTP 请求可能还在跑，只是你拿到的 CompletableFuture 被标记为 TimeoutException 了。
- 常见错误现象：
orTimeout(3, TimeUnit.SECONDS)后仍观察到线程池里有未结束的 HTTP 连接，日志显示请求实际耗时 8 秒 - 根本原因：
orTimeout是“结果层面”的超时，不是“执行层面”的取消；它不会调用cancel(true)，也不会向底层ExecutorService或 HTTP 客户端发中断信号 - 适用场景：适合纯计算型异步任务（比如
supplyAsync做本地数据处理），或你明确信任下游已支持响应式取消（如某些新版HttpClient）
HTTP 异步调用必须配合 cancel(true) 才算真正超时
要让超时真正生效，得让异步操作感知并响应中断。以 HttpClient 为例，它支持 HttpRequest.Builder::timeout，但这个 timeout 只对连接和响应阶段有效，不覆盖整个 CompletableFuture 生命周期。所以你需要两层控制：
- 在
CompletableFuture上链式调用orTimeout触发失败路径 - 在
thenApply/exceptionally之外，显式监听完成状态，对未完成的 future 调用cancel(true) - 确保底层 HTTP 调用使用支持中断的客户端（如
java.net.http.HttpClient，而非老版HttpURLConnection或未配置 cancel 的 OkHttp）
简短示例：
CompletableFuture<HttpResponse<String>> future =
CompletableFuture.supplyAsync(() -> {
try {
return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}, executor);
future.orTimeout(3, TimeUnit.SECONDS)
.whenComplete((res, ex) -> {
if (ex instanceof TimeoutException && !future.isDone()) {
future.cancel(true); // 关键：主动中断 supplyAsync 中的阻塞操作
}
});
orTimeout 和 completeOnTimeout 的关键区别在哪
这两个方法都处理超时，但语义完全不同，选错会导致业务逻辑出错：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
-
orTimeout：超时时抛TimeoutException，future 进入异常完成态；后续thenApply不会执行，exceptionally会被触发 -
completeOnTimeout：超时时用你指定的默认值「正常完成」future；后续thenApply仍会执行，容易掩盖真实失败 - 性能影响：两者都不额外开线程，但
completeOnTimeout可能让你误以为请求成功返回了默认值（比如空 JSON），而实际服务根本没响应 - 典型踩坑：用
completeOnTimeout(null)做兜底，结果thenApply里直接 NPE，还查不到超时日志
CompletableFuture 超时 + 重试组合时要注意什么
加了 orTimeout 后再套 handle 或 exceptionally 做重试，很容易重复提交请求：
- 问题根源：如果第一次请求因网络延迟还没返回，
orTimeout已触发，但此时原始supplyAsync仍在运行；重试逻辑又发起新请求，造成“幽灵请求” - 解决办法：用
AtomicBoolean或CompletableFuture自身状态（isDone()/isCancelled()）做幂等判断，只在真正需要时重试 - 兼容性注意：Java 9+ 才有
orTimeout，若项目需兼容 Java 8，别硬套，改用Future+get(timeout)+cancel(true)组合更稳妥
真正难的不是写超时代码，是确认每个环节——从线程中断信号、HTTP 客户端行为、到连接池回收——都对 cancel(true) 有响应。漏掉任意一环，超时就只是个假动作。
