Java CompletableFuture.orTimeout 怎样设置异步超时

给一个异步调用设置上限时，Java 9 及更高版本可以直接在 CompletableFuture 上调用 orTimeout：

CompletableFuture future = loadProfile();
future.orTimeout(800, TimeUnit.MILLISECONDS);
// 注释：在 800 毫秒内没有完成时，future 会以 TimeoutException 异常完成。

它的关键点有两个：方法返回的仍是原来的 future，超时体现为异常完成而不是一个默认字符串；另外，orTimeout 不负责中断或停止底层任务。下面按参数、结果和边界把这几个细节拆开。

最小写法：把时间上限挂到同一个 Future 上

orTimeout(timeout, unit) 的返回值是当前 CompletableFuture 本身，所以可以直接链式调用，也可以先保存任务再设置超时。任务在时限内正常完成时，原来的结果照常向下游传播；只有任务还没有完成，超时动作才会让它异常完成。

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

public class AsyncTimeoutDemo {
    static CompletableFuture loadProfile() {
        return CompletableFuture.supplyAsync(() -> {
            // 注释：这里代表远程调用或其他异步工作，不在示例中执行真实网络请求。
            return "profile-data";
        });
    }

    static CompletableFuture loadWithTimeout() {
        // 注释：timeout 使用毫秒，TimeUnit 负责解释数值的时间单位。
        return loadProfile().orTimeout(800, TimeUnit.MILLISECONDS);
    }
}

这里不需要额外创建一个定时线程去轮询状态。JDK 的 CompletableFuture 已经提供了延时和超时相关的适配能力，调用方只需把业务允许的等待时间表达清楚即可。

timeout 和 TimeUnit 怎么传才不容易出错

第一个参数是 long 类型的等待时长，第二个参数是解释它的 TimeUnit。例如 800, MILLISECONDS 表示 800 毫秒，2, SECONDS 表示 2 秒。不要把配置中的“毫秒数字”直接当成秒传入，否则超时窗口会被放大一千倍。

long timeoutMs = 800L;
if (timeoutMs  future = loadProfile()
        .orTimeout(timeoutMs, TimeUnit.MILLISECONDS);
// 注释：TimeUnit.MILLISECONDS 让 timeoutMs 的含义保持明确，避免单位漂移。

TimeUnit 不能省略，传入空值也不应被当成默认单位。实际项目中可以在配置解析层统一把秒、毫秒转换成一个带单位的策略对象，再在调用边界处调用 orTimeout。这样更容易审查每个外部依赖的等待上限。

超时不等于底层任务已经停止

这是最容易被误解的地方。orTimeout 改变的是这个 CompletableFuture 的完成状态：超过期限后，下游看到的是 TimeoutException。它不会自动中断正在执行的供应函数，也不会替你关闭数据库连接、HTTP 响应体或其他外部资源。

因此，超时处理应当拆成两层：第一层是对调用方快速返回或降级；第二层是让底层任务具备自己的取消、截止时间和资源清理机制。只设置第一层，可能出现调用方已经返回，但后台工作仍继续占用线程和连接。

用 handle 或 exceptionally 处理 TimeoutException

如果超时属于可降级情况，可以在链尾统一处理；如果超时需要单独记录指标，则用 handle 同时观察结果和异常。调用 join 时，异常完成通常会以 CompletionException 包裹原始异常，因此读取原因时要多看一层。

CompletableFuture safeFuture = loadProfile()
        .orTimeout(800, TimeUnit.MILLISECONDS)
        .handle((value, error) -> {
            if (error == null) {
                // 注释：正常完成时保留原始业务结果。
                return value;
            }

            Throwable cause = error;
            if (cause instanceof java.util.concurrent.CompletionException
                    && cause.getCause() != null) {
                // 注释：join 或异步链可能包装异常，先取出真实原因。
                cause = cause.getCause();
            }
            if (cause instanceof java.util.concurrent.TimeoutException) {
                // 注释：超时走明确的降级值，避免把所有异常都吞掉。
                return "profile-timeout-fallback";
            }
            // 注释：非超时异常继续抛出，不能伪装成超时。
            throw new java.util.concurrent.CompletionException(cause);
        });

String result = safeFuture.join();
// 注释：此处拿到的是正常值或降级值，非超时异常仍会向上抛出。

只想处理超时而不改变其他异常语义时，也可以在 exceptionally 中先判断原因。无论选择哪种方式，都应把超时计数、调用对象和实际等待上限写入日志或指标，避免只看到一个笼统的“异步失败”。

什么时候改用 completeOnTimeout

orTimeout 适合“超时就是失败，需要重试、降级或告警”的场景；completeOnTimeout 则会在超时后用指定值正常完成。两者都属于给同一个 future 添加时间边界，区别在于下游看到的是异常还是默认结果。

常见问题

调用 orTimeout 后还要重新接收返回值吗？

不强制需要。官方 API 返回当前的 CompletableFuture，所以可以链式写，也可以把返回值赋给另一个变量增强可读性。

超时后还能拿到原来的异步结果吗？

对同一个 future 来说，超时已经把它置为异常完成；如果业务仍需要后台任务结果，应另外设计独立的任务生命周期和结果存储，不能把调用方的超时当成任务取消。

为什么 join 抛出的不是直接的 TimeoutException？

join 对异常完成使用非受检的 CompletionException 包装，判断业务原因时读取它的 getCause()，再区分 TimeoutException 与其他异常。

最终可以把规则记成一句话：用 orTimeout(时长, 单位) 给异步结果设置失败上限，用 handle 或 exceptionally 处理超时，用任务自身的取消和资源治理解决“底层工作是否继续”的问题。