Java completeOnTimeout 和 orTimeout 怎么选择

给 CompletableFuture 增加超时时，最重要的不是“哪个方法更短”，而是超时在你的业务里究竟算一个可接受结果，还是一次必须暴露的失败。如果超时后可以返回缓存、默认配置或降级数据，选 completeOnTimeout；如果超时需要触发重试、告警、熔断或明确失败，选 orTimeout。

Oracle Java 26 API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/CompletableFuture.html

一、两种方法代表两种超时模式

这两个方法都从 Java 9 开始提供，也都会返回当前这个 CompletableFuture。真正的差异发生在超时时刻：completeOnTimeout(value, timeout, unit) 尝试用指定值让 Future 正常完成；orTimeout(timeout, unit) 则尝试让它以 TimeoutException 异常完成。

因此，一个简单但很可靠的判断是：如果你不希望下游把超时误当成成功，就不要用普通兜底值掩盖它。

二、什么时候选择 completeOnTimeout

completeOnTimeout 适合“及时返回比拿到最新结果更重要”的读取场景。例如商品推荐接口在 300 毫秒内没有得到实时结果，可以返回缓存推荐；配置中心暂时不可用时，可以使用本地默认配置。此时兜底值不是伪造成功，而是产品已经认可的服务降级。

这个模式的优势是下游代码简单：Future 正常完成后，后续的转换、聚合和响应构造可以沿正常链路继续执行。但代价也很明确：如果兜底对象和实时对象长得完全一样，监控和业务代码就很难区分“真实结果”与“超时降级”。

更稳妥的做法是让返回对象携带来源信息，例如 source=CACHE、stale=true 或 degraded=true，并单独记录超时兜底指标。这样既保留正常完成的便利，也不会把降级事实藏起来。

三、什么时候选择 orTimeout

当超时本身会影响正确性，应该优先选择 orTimeout。支付确认、库存扣减、订单写入、权限校验等操作，不能因为等待太久就随便构造一个“看起来成功”的值。让 Future 以 TimeoutException 异常完成，调用方才能明确执行重试、补偿、告警或返回超时状态。

orTimeout 也更适合需要按异常类型统计的基础设施层。超时、网络失败和业务拒绝可以分别计数，而不是全部被压缩成一个默认值。需要注意的是，join() 通常会把底层异常包装为 CompletionException，get() 则会通过 ExecutionException 暴露原因，判断时应先解包。

四、典型实现：把兜底和失败写清楚

合法兜底场景可以直接写成正常完成模式：

CompletableFuture quoteFuture = CompletableFuture
    .supplyAsync(() -> priceService.query(productId), executor)
    // 缓存报价是产品允许的降级结果，因此超时后正常完成。
    .completeOnTimeout(Quote.cached(productId), 300, TimeUnit.MILLISECONDS);

Quote quote = quoteFuture
    // 正常结果和降级结果都走同一条规范化链路。
    .thenApply(this::normalize)
    .join();

如果超时必须被调用方感知，就保留异常语义：

CompletableFuture resultFuture = CompletableFuture
    .supplyAsync(() -> remoteService.fetch(), executor)
    // 300 毫秒后仍未完成，就以 TimeoutException 异常完成。
    .orTimeout(300, TimeUnit.MILLISECONDS)
    .handle((value, error) -> {
        if (error == null) {
            return value;
        }

        // join/异步阶段可能包装异常，先还原根因再分类处理。
        Throwable cause = error instanceof CompletionException
            ? error.getCause()
            : error;

        if (cause instanceof TimeoutException) {
            return "TIMEOUT";
        }
        throw new CompletionException(cause);
    });

上面的 handle 示例把超时转换成了字符串状态，适用于边界层；在领域层通常更推荐继续保留异常，让上层决定 HTTP 状态码、重试策略或补偿动作。

五、反例：不要把 null 当万能兜底

最常见的误用是 completeOnTimeout(null, ...)。它确实能让代码快速“跑通”，但下游看到的只是正常完成的 null，无法判断这是远端真的返回空、数据不存在，还是请求超时。最终往往在更远的位置出现 NullPointerException，使问题更难定位。

只有当 null 在接口契约中本来就有唯一且明确的含义时才考虑这样做。更好的方案是使用带状态的领域对象、Optional，或直接使用 orTimeout 保留失败事实。

六、超时完成不等于停止底层任务

这两个方法控制的是 CompletableFuture 的完成状态，不是执行线程的生命周期。当超时调度先赢得完成竞争时，原来的 Supplier 仍可能在线程池里继续运行，继续占用连接、CPU 或其他资源。即使调用 cancel(true)，CompletableFuture 的 mayInterruptIfRunning 参数也不会像传统 FutureTask 那样保证中断计算。

如果底层调用必须被终止，需要在任务本身设计可取消机制，例如为 HTTP 客户端设置请求级超时、关闭可取消句柄、传递取消令牌，或者让循环任务定期检查中断/取消状态。不要把 orTimeout 当成资源回收器。

七、共享同一个 Future 会带来什么后果

completeOnTimeout 和 orTimeout 都返回当前对象，而不是创建一个隔离的包装 Future。下面的比较结果是 true：

CompletableFuture source = CompletableFuture
    .supplyAsync(() -> remoteService.fetch(), executor);

CompletableFuture timed = source.orTimeout(300, TimeUnit.MILLISECONDS);

// orTimeout 返回的是同一个 CompletableFuture 实例。
System.out.println(source == timed); // true

这意味着共享了 source 的其他调用方也会观察到超时异常。若多个线程、底层任务和超时调度同时竞争完成，只有第一次成功完成会生效。把两个超时方法连续挂到同一个 Future 上，通常只会制造难以解释的时间竞争；应先确定一种业务语义，再配置一个清晰的超时策略。

八、选择清单与常见问题

• 兜底值能否被当成合法业务结果？能，优先 completeOnTimeout；不能，优先 orTimeout。
• 下游是否必须区分超时、网络错误和业务错误？必须区分时选择 orTimeout。
• 是否需要无异常地继续组合多个 Future？可以使用 completeOnTimeout，但兜底对象必须可识别。
• 底层任务超时后是否必须停止？无论选哪一个，都要额外设计请求超时或取消机制。
• 这个 Future 是否被多个调用方共享？如果是，要意识到超时会改变同一个对象的最终状态。

orTimeout 和 get(timeout) 一样吗？

不一样。get(timeout, unit) 是调用线程最多等待指定时间；等待超时会抛出 TimeoutException，但原 Future 可以继续保持未完成并稍后成功。orTimeout 则是在期限到达时尝试把原 Future 本身异常完成，因此其他观察者也会看到这个最终状态。

已经用了 HTTP 客户端超时，还需要这两个方法吗？

两者控制的层级不同。HTTP 超时负责限制网络请求生命周期；CompletableFuture 超时负责限制异步编排愿意等待多久。实际系统常同时设置两层，但要让时间预算有先后关系，并避免上层早已超时、下层请求仍长时间占用资源。

最终可以把选择压缩成一句话：合法降级走 completeOnTimeout，必须暴露的超时失败走 orTimeout；两者都不负责自动停止底层任务。