Java CompletableFuture 怎样给链路加超时回退

异步调用最怕的不是失败，而是一直没有结果：上游接口慢下来后，线程会继续等待，调用方也不知道应该继续返回、记录超时，还是换一个保守结果。Java 的 CompletableFuture 已经提供了两种不同语义的超时方法，关键是不要把它们混成同一种“超时配置”。

本文用一个字符串查询链路说明：需要保留超时异常时用 orTimeout，需要把超时转换成业务默认值时用 exceptionally，而超时本来就等于默认值时可以直接用 completeOnTimeout。

官方文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/CompletableFuture.html

先判断你需要的是超时异常还是默认值

先看调用方能不能接受一个普通结果。如果超时意味着依赖不可用、需要打点或触发降级，就保留异常；如果业务已经定义“超时等于推荐值、空列表或缓存值”，则可以直接完成为默认值。Oracle 的 API 文档明确区分了这两个方法：orTimeout 在期限内没有完成时异常完成，completeOnTimeout 则用给定值正常完成。

因此，下面这张判断表比“统一给所有请求加一个超时”更可靠：

用 orTimeout 给异步链路加明确边界

orTimeout 返回的仍然是同一个 CompletableFuture，它不会替你取消底层任务。超时只改变 future 的完成状态；底层 HTTP 客户端、数据库驱动或自定义任务是否停止，仍要由对应依赖提供取消或连接超时。

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

public class TimeoutBoundary {
    static CompletableFuture queryRemote() {
        // 示例只表达异步链路；实际项目应在远端客户端自身配置连接和读取超时。
        return CompletableFuture.supplyAsync(() -> "remote-value");
    }

    static CompletableFuture withTimeout() {
        // 800 毫秒后让 future 以 TimeoutException 异常完成，便于上层区分超时。
        return queryRemote().orTimeout(800, TimeUnit.MILLISECONDS);
    }
}

这里的 800 毫秒只是示例边界，不代表所有接口都应该使用同一个值。读者真正要固定的是“从提交任务到调用方收到结果”的预算，并把连接建立、读取、重试和回退耗时一起算进来。

用 exceptionally 把 TimeoutException 转成可用回退

当超时要转成默认值时，可以在 orTimeout 后接 exceptionally。这个回退函数会收到异常对象，因此可以只处理 TimeoutException，其余异常继续以 CompletionException 传播，避免把真正的代码错误伪装成“没有数据”。

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

static CompletableFuture queryWithFallback() {
    return queryRemote()
        // 先保留超时异常，后面的 exceptionally 才能判断异常类型。
        .orTimeout(800, TimeUnit.MILLISECONDS)
        .exceptionally(error -> {
            // CompletionException 可能包着真正原因，需要逐层取出 cause。
            Throwable cause = error;
            while (cause instanceof CompletionException && cause.getCause() != null) {
                cause = cause.getCause();
            }
            if (cause instanceof TimeoutException) {
                // 超时回退要带来源语义，避免和远端真实返回的空字符串混淆。
                return "fallback-value";
            }
            // 非超时异常继续失败，不能把程序错误静默吞掉。
            throw new CompletionException(cause);
        });
}

这个写法的重点不是把所有异常都吃掉，而是只把可预期的超时映射为可解释的回退。实际项目可以把回退值包装成带 source=FALLBACK 的对象，或者同时写入结构化日志。

超时本来就是默认值时，用 completeOnTimeout

如果业务契约已经规定“规定时间内查不到就使用固定值”，可以减少一层异常转换：

static CompletableFuture queryOrDefault() {
    return queryRemote()
        // 超时直接产生正常结果；适合默认值本身就是业务允许的结果。
        .completeOnTimeout("fallback-value", 800, TimeUnit.MILLISECONDS);
}

这种方式更简洁，但也隐藏了“曾经发生过超时”这一事实。若监控、计费或用户提示需要知道结果来自回退，就不要只返回裸字符串，应该返回包含值和来源的结果对象，或在链路旁记录指标。

发布前检查这几个容易漏掉的边界

• 不要把 orTimeout 当成底层任务取消；远端客户端仍需配置自己的连接、读取和取消策略。
• 不要对所有异常统一返回默认值；至少区分 TimeoutException、取消和程序错误。
• 不要在回退分支里再次调用同一个慢依赖，否则超时预算会被重新消耗。
• 如果回退动作本身会阻塞，把它放进明确的业务线程池，并记录超时原因和回退来源。

最后可以按三句话复查：超时是否需要被观测？回退是否是业务允许的正常结果？底层任务是否有自己的取消边界？前两题决定选择哪个 API，第三题决定这条链路是否真的能控制资源。

常见问题

orTimeout 会自动停止正在执行的任务吗？

不会。它改变的是 CompletableFuture 的完成状态，底层任务的停止需要依赖实际执行器或客户端支持取消。

为什么 exceptionally 没有捕获到我想处理的异常？

先检查异常是否被 CompletionException 包装，再沿着 getCause() 查看根因；同时确认该阶段确实以异常完成，而不是使用 completeOnTimeout 正常完成。