Java CompletableFuture 超时怎么区分：orTimeout、completeOnTimeout 与线程池回收

线上订单详情偶尔要等几秒，调用方却在 800 毫秒后拿到一个看似正常的“暂无库存”。问题通常不在于有没有设置超时，而在于把 orTimeout 和 completeOnTimeout 当成了同一种开关：前者让阶段失败，后者给阶段补一个默认结果。两者都不会自动中断已经开始的底层任务，线程池也不能因此直接当作空闲。

需要保留失败语义时选 orTimeout；业务允许降级时选 completeOnTimeout。无论选哪一个，都要单独处理底层任务的取消、资源释放和线程池容量。

先把两种超时放进同一个订单场景

假设库存服务返回一个 StockResult，查询动作可能卡在网络等待。订单页可以有两种产品选择：库存是核心条件，查不到就明确报错；库存只是推荐信息，查不到仍然展示订单主体。

CompletableFuture stock = CompletableFuture.supplyAsync(
    () -> stockClient.query("SKU-42"), pool);

CompletableFuture strict = stock
    .orTimeout(800, TimeUnit.MILLISECONDS);

CompletableFuture fallback = stock
    .completeOnTimeout(StockResult.unknown(), 800, TimeUnit.MILLISECONDS);

两个方法都返回同一个阶段对象，计时从方法挂上去开始。区别在于 800 毫秒到达时，strict 会进入异常完成，fallback 会带着 unknown 进入正常完成。不要只看页面上有没有响应，要把这个状态差异写进测试。

orTimeout 的异常会怎样穿过后续链路

orTimeout 适合“数据缺失不能被伪装成成功”的路径。它不会返回一个空对象，而是让阶段异常完成，因此 thenApply 不会继续执行，异常会在 exceptionally、handle 或调用方的 join 处显现。

strict.handle((value, error) -> {
    if (error == null) {
        return render(value);
    }
    Throwable cause = error instanceof CompletionException
        ? error.getCause() : error;
    if (cause instanceof TimeoutException) {
        return renderTimeout();
    }
    return renderFailure(cause);
});

这里要先剥掉可能包裹异常的 CompletionException，再判断 TimeoutException。如果直接把所有异常都转成“暂无库存”，网络故障、服务端错误和真实空库存就会混在一起，后续告警也失去意义。

completeOnTimeout 适合什么样的降级

推荐信息、画像标签、非关键计数这类字段可以接受一个明确的备用值。备用值最好带有状态，而不是简单返回 null，这样页面和日志能区分“确实为零”和“查询超时”。

备用结果不是“调用已经结束”的证明。计时器只负责完成 CompletableFuture；如果 stockClient.query 还在阻塞，供应商连接和工作线程仍可能被占用。对 HTTP 客户端要设置自己的请求超时，对数据库要配置查询或连接超时，不能只依赖外层阶段。

超时后底层任务为什么还可能继续

可以用一个带计数器的本地任务做验证：阶段 100 毫秒超时，任务 2 秒后才打印“底层结束”。如果两条日志都出现，就说明观察层已经超时，但供应任务并没有被自动打断。

AtomicBoolean finished = new AtomicBoolean();
CompletableFuture task = CompletableFuture.supplyAsync(() -> {
    try {
        Thread.sleep(2000);
        finished.set(true);
        return "remote-ok";
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        return "interrupted";
    }
}, pool);

task.orTimeout(100, TimeUnit.MILLISECONDS)
    .whenComplete((value, error) -> logState(value, error));

生产代码需要把取消动作和具体客户端绑定：调用支持取消，就在超时分支调用它；调用不支持取消，就限制并发、缩短底层等待并记录任务最终结束时间。只给外层阶段加超时，可能让请求更快返回，却让线程池慢慢堆满。

用三个检查点验收，不要只断言返回字符串

1. 阶段状态：严格模式应为异常完成，降级模式应为正常完成并携带备用状态。
2. 异常链路：严格模式能识别 TimeoutException，其他异常不能被误报成超时。
3. 资源结果：等待足够长时间后确认底层任务结束，线程池活动数回到预期范围。

测试里不要用固定的“睡一秒再看”来掩盖竞态。可以使用 CountDownLatch 控制底层任务何时放行，再分别断言阶段结果和任务收尾信号。这样失败时能知道是计时语义错了，还是取消/回收没有发生。

常见问题

orTimeout 会自动取消 HTTP 请求吗？

不会。它改变 CompletableFuture 的完成结果；HTTP 客户端是否停止，要看客户端自己的超时和取消能力。

备用值应该用 null 吗？

不建议。用带状态的对象表达“未知或超时”，能避免把超时误判为真实空值。

两个方法可以连续使用吗？

可以，但要先写清优先级。通常一个阶段先确定严格失败还是业务降级，连续叠加会让维护者难以判断最终语义。

把超时语义写进接口契约

CompletableFuture 的超时方法解决的是“调用方何时得到阶段结果”，不是所有底层资源的生命周期。核心数据用 orTimeout 保留失败信号，可降级信息用 completeOnTimeout 返回带状态的备用值；同时为网络、数据库和线程池设置各自的回收边界。最后用阶段状态、异常链和底层任务收尾三组断言验收，超时才不会从一个参数问题变成隐蔽的资源问题。