CompletableFuture 超时怎样让超时任务停止等待并返回备用值为什么结果为空或不符合预期

想让 CompletableFuture 在等待超时后给出备用值，可以用 completeOnTimeout；它只规定结果对象怎样完成，不负责停止底层计算。结果为空时，先排查任务是否正常返回了 null、是否用了 runAsync，以及异常处理是否把错误转换成 null。

下面以 Java 21 为环境给出可保存的示例。处理目标是约束调用方等待，并保留对慢任务的观察能力。示例没有在本文环境执行，输出描述是代码语义说明。

1. 从空值和异常类型判断触发信号

先辨别“没有结果”和“拿到 null”：runAsync 返回 CompletableFuture，正常完成后的 join 本来就是 null；supplyAsync 的 supplier 也允许返回 null。已经正常完成的 null 不会因为配置备用值而被替换。

不要直接把所有异常统一改成空字符串：这会使真正的下游故障在业务侧看起来像正常空数据。

2. 给调用方建立独立的超时结果

completeOnTimeout 在尚未完成时以备用值正常完成当前 Future；orTimeout 则使当前 Future 以超时异常完成。两者都返回自身。如果源对象还被缓存、日志或其他调用方共享，先创建 copy 副本，再给副本设置本次响应策略。copy 不是新的后台任务，副本完成也不会撤回源任务。

把下面代码保存为 TimeoutFallback.java。源任务、原始 Future、copy 副本、超时策略、备用值与调用方分别对应图中的两个边界。

import java.util.concurrent.*;

public class TimeoutFallback {
    public static void main(String[] args) {
        ExecutorService workers = Executors.newFixedThreadPool(1);
        try {
            CompletableFuture source =
                CompletableFuture.supplyAsync(() -> {
                    try {
                        // 模拟慢调用，不代表真实网络客户端
                        Thread.sleep(500);
                        return "remote-value";
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        throw new CompletionException(e);
                    }
                }, workers);

            // 副本单独承载响应超时，保留源结果的观察能力
            CompletableFuture response = source.copy()
                .completeOnTimeout("fallback-value", 50, TimeUnit.MILLISECONDS);

            System.out.println("response=" + response.join());
            // 此处会等待源任务，用于演示两个结果对象彼此不同
            System.out.println("source=" + source.join());
        } finally {
            // 示例结束后关闭线程池；关闭动作不等同于中断正在运行的调用
            workers.shutdown();
        }
    }
}

# 编译并执行示例，使用 Java 21 的命令行环境
javac TimeoutFallback.java
java TimeoutFallback

源任务被故意延迟，通常 response 行会显示 fallback-value，source 行随后显示 remote-value。线程调度不是精确计时保证：若两种完成条件接近，哪个先成功完成对象就决定最终值，不应把一次演示输出当作硬实时测试。第二次 join 是教学观察点，实际接口不要在返回备用值后又同步等待源任务。

3. 把返回备用值与资源停止分开处理

响应 Future 与备用结果属于响应对象；工作线程、阻塞调用、客户端超时与取消句柄属于资源控制。线程池仍繁忙时，需要对真实 HTTP、数据库或其他客户端设置连接、读取或请求期限，并按客户端契约保留取消句柄。阻塞调用能否被终止取决于其具体实现。

CompletableFuture.cancel(true) 不保证中断 supplier 所在线程；不能据此承诺任务已停止。即使使用支持中断的工作提交方式，底层库也必须响应中断，并在退出路径释放资源。副本超时后，原任务的写数据库、发消息等副作用仍可能发生，写操作还要结合幂等与业务取消协议处理。

如果备用值只用于超时，其他异常应保持可见；completeOnTimeout 本身不会吞掉先发生的业务异常。若额外使用 exceptionally，请只处理明确允许降级的异常，其余继续传播，同时记录原因。

4. 保留回退路径并观察降级比例

上线时把等待期限、备用值与降级开关纳入配置。发生错误率上升时，可以回退到此前已验证的处理策略；不要盲目移除期限或无限拉长等待，这可能让线程、连接和队列压力继续累积。

记录请求总数、备用响应次数、源任务结束耗时、线程池活动数、队列长度和底层客户端超时。只看接口耗时下降会遗漏后台资源持续消耗。本文未提供虚构的线上指标；应在实际系统中比较相同负载下的这些信号。

为什么配置了备用值仍然返回 null？

正常 null 已经完成对象，备用值不会覆盖它。先修正 supplier 的返回契约，或用 thenApply 对合法空值作业务映射。

为什么 orTimeout 后没有获得备用值？

它的语义是异常完成。需要正常备用结果时选 completeOnTimeout，或明确区分超时异常后再转换。

多个调用方可以共用同一超时 Future 吗？

只有期限和降级策略确实相同时才考虑共享。不同调用方使用各自副本，可以避免一个调用方的期限改变其他调用方所见结果，但共同源任务的资源预算仍需单独管理。

Java 21 官方 API 地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/CompletableFuture.html。可查 completeOnTimeout、orTimeout、copy 与 cancel 的具体约定。