Java CompletableFuture 超时怎么处理：orTimeout、completeOnTimeout 与取消边界实战

订单详情接口把上游库存查询包进 CompletableFuture 后，接口的 P95 从 180ms 变成了 420ms。最容易误判的地方是：给 Future 加上 300ms 超时，只能让调用方更早拿到结果或异常，并不自动让已经开始的后台计算停下来。

先把“返回超时”和“任务停止”分开

这两个动作在监控上经常挨着出现，语义却完全不同。调用方只关心 300ms 内能不能拿到库存结果；后台任务还可能继续占用连接、CPU资源，甚至在2秒后才把结果写进日志里。

Oracle 的官方 Javadoc 明确说明，CompletableFuture.cancel 在当前实现里只是把 Future 以取消异常完成，mayInterruptIfRunning 参数不会主动用中断控制任务的处理过程。排查问题的时候要同时观察 Future 状态和实际工作线程的结束时间，不能只看接口返回。

用 orTimeout 让失败尽快回到接口层

如果库存查询超时就直接让请求失败，或者进入统一的降级分支，直接使用 orTimeout 就可以。它会在设定的时间到达后，让原 Future 以异常状态完成；如果上游业务先返回了正常结果，超时动作不会覆盖已经拿到的正常返回值。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

CompletableFuture stock = CompletableFuture
    .supplyAsync(() -> queryStock("SKU-1001"))
    .orTimeout(300, TimeUnit.MILLISECONDS);

String result = stock.handle((value, error) -> {
    if (error == null) {
        return value;
    }
    if (error.getCause() instanceof java.util.concurrent.TimeoutException) {
        return "STOCK_TIMEOUT";
    }
    return "STOCK_ERROR";
}).join();

这里要注意的检查点是 handle 收到的异常。异步链路里常见的情况是 CompletionException 包住了真实的异常原因，所以不要只对比最外层异常的类型就下定论。

需要可用结果时，用 completeOnTimeout 返回降级值

商品详情里的推荐库存、用户画像这类非核心字段，没必要为了它让整个接口直接失败。这时候可以把超时转换为一个明确的降级值，但要让下游逻辑能识别出它不是本次实时查询的结果。

CompletableFuture recommendation = CompletableFuture
    .supplyAsync(() -> loadRecommendation("user-42"))
    .completeOnTimeout("RECOMMENDATION_STALE", 200, TimeUnit.MILLISECONDS);

recommendation.thenAccept(value -> {
    boolean stale = "RECOMMENDATION_STALE".equals(value);
    recordMetric("recommendation.result", stale ? "stale" : "fresh");
});

降级值最好是业务上可识别的特殊状态，不要随手写一个空字符串。空字符串会把“确实没有推荐内容”和“查询超时”这两种不同场景混在一起，后续想要统计超时占比的时候根本分不清楚。

cancel(true) 为什么没有让睡眠中的任务停下

下面这个小实验能直接看清楚边界：Future 在100ms后被标记为取消，但任务本身每100ms打印一次心跳，直到自身的循环逻辑走完才会结束。

CompletableFuture task = CompletableFuture.supplyAsync(() -> {
    try {
        for (int i = 1; i 

输出里的 cancelled=true 只说明结果容器已经进入取消状态。如果线程池里的心跳日志还在持续打印，就说明底层工作没有收到可以执行的停止信号。这时候别着急把超时数值再调小，先确认任务本身是不是做了中断检查、有没有配置连接超时、finally块里有没有做资源清理。

把真正的停止动作放进任务内部

如果任务是批量读取、分页扫描或者循环计算，应该在合适的执行边界检查中断状态。当阻塞调用本身抛出 InterruptedException 时，先恢复中断标记再结束任务；数据库连接、文件句柄这类资源统一放进 finally 块里做回收。

String scanPages() {
    try {
        for (int page = 1; page 

这种处理也不是万能的。如果任务卡在没有配置超时的网络读取里，单纯检查中断状态也没有机会执行；对应的连接客户端必须自带读取超时配置，或者使用支持主动取消的调用模型。

上线前用三组信号做反向验证

建议先用1秒延迟的模拟假上游做压测，再把延迟逐步调整到50ms。每次只改一个条件，记录下请求耗时、Future完成时间和工作线程最后一条日志，才能判断当前实现是做到了“调用方快返回”，还是真的做到了“后台任务资源收敛”。

常见问题

orTimeout 和 completeOnTimeout 能同时使用吗？

可以同时调用，但它们会竞争同一个 Future 的完成权，先触发的动作会最终生效。业务场景里通常二选一，能让异常和降级的语义更清晰，不会出现逻辑冲突。

completeOnTimeout 会取消上游查询吗？

不会。它只是让 Future 在超时后填充一个预设值完成，上游的计算是否停止，仍然取决于任务本身和底层客户端的取消能力。

为什么日志里出现了超时，线程数却没有下降？

因为超时可能只发生在结果返回层。检查线程池队列、任务内部心跳和网络读取超时配置，确认后台任务是不是还在占用资源没有退出。

什么时候应该改用 FutureTask 或结构化并发？

如果必须可靠地控制单个工作线程的中断，或者多个子任务需要绑定同一个生命周期，可以评估 FutureTask 或结构化并发方案；CompletableFuture 更适合表达结果依赖和多任务组合的场景。

小结：给超时策略配一条可观察的停止路径

orTimeout 解决的是异常返回，completeOnTimeout 解决的是可接受的降级值，cancel 只改变 CompletableFuture 的结果状态。把三者和任务内部的中断检查、客户端读取超时、finally 清理以及线程池指标放在同一张检查表里，线上才不会出现接口已经返回、后台工作却越积越多的假成功情况。