CompletableFuture 超时怎样让超时任务停止等待并返回备用值怎样完成一个可复用的最小示例

如果调用方只需要在 800 毫秒内得到一个可用结果，最小写法是给 CompletableFuture 加上 completeOnTimeout：期限内完成就返回真实值，超时就返回备用值。但要先划清一个容易误解的边界：这个方法结束的是调用方等待的 future，不是强制杀掉正在执行的 supplier。要让后台工作真正停下来，任务必须支持中断或显式取消。

官方地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/CompletableFuture.html

下面把超时当成并发资源的保护边界来处理：保护请求延迟预算，避免无意义地继续占用线程池，同时保留真实结果、备用值和异常的可追踪性。

先确定超时要保护什么

超时策略通常同时保护三件事：调用方最多等待多久、线程池还能承受多少慢任务、业务在拿不到真实结果时允许返回什么。备用值应该是明确的降级结果，例如“暂无推荐”或空的只读配置，不能把半成品当成成功数据。

还要把两个动作分开：completeOnTimeout 让 future 在期限到达时以给定值正常完成；orTimeout 则让 future 以 TimeoutException 异常完成。两者都解决“调用方不要无限等待”，都不自动保证后台计算立刻停止。

用 completeOnTimeout 返回备用值

下面的包装方法只负责控制调用方的等待结果。它用自定义线程池承载阻塞型工作，避免把外部 I/O 随意塞进公共线程池；备用值也作为参数传入，便于不同调用场景复用。

import java.time.Duration;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;

public final class TimeoutFallback {
    private TimeoutFallback() {
        // 工具类不需要实例化，避免把策略状态藏在对象里。
    }

    public static  CompletableFuture withFallback(
            java.util.function.Supplier supplier,
            Executor executor,
            Duration budget,
            T fallback) {
        // 阻塞型 supplier 使用明确的业务线程池，避免挤占公共线程池。
        return CompletableFuture.supplyAsync(supplier, executor)
                // 期限内已有真实结果时保留真实结果，超时才使用备用值。
                .completeOnTimeout(fallback, budget.toMillis(),
                        java.util.concurrent.TimeUnit.MILLISECONDS);
    }
}

调用方可以把结果来源一并包装出来，避免后续把备用值误当成远端真实数据。实际项目里还应给 supplier 增加请求级 traceId，并记录预算、完成耗时和结果来源。

CompletableFuture result = TimeoutFallback.withFallback(
        () -> loadProfileFromRemote(),
        profileExecutor,
        Duration.ofMillis(800),
        "profile-unavailable");

// join 只等待已经被超时策略保护过的 future，不再额外设置无限等待。
String profile = result.join();

为后台任务设计协作式停止

如果 supplier 只是等待一个不可中断的远端调用，future 返回备用值后，后台任务可能仍然占用线程。这里真正要控制的是任务本身：让它在循环、批处理分段或可中断 I/O 返回处检查取消信号，并在退出前释放连接、文件句柄和临时对象。

不要把 cancel(true) 写成“保证停止”。官方 API 说明 CompletableFuture 没有直接控制产生结果的计算，取消表现为异常完成；它是否能让底层工作停止，取决于实际任务和执行器的配合。对不可中断的阻塞调用，应优先使用客户端自己的超时参数。

public final class CancellableWork {
    public static String loadInChunks(java.util.List chunks,
                                      java.util.concurrent.atomic.AtomicBoolean cancelled) {
        StringBuilder merged = new StringBuilder();
        for (String chunk : chunks) {
            // 每个分段都检查取消信号，避免超时后继续无边界地处理数据。
            if (cancelled.get() || Thread.currentThread().isInterrupted()) {
                throw new java.util.concurrent.CancellationException("work cancelled");
            }
            merged.append(chunk);
        }
        // 返回前只交付完整结果，避免把半成品写入共享缓存。
        return merged.toString();
    }
}

可复用的做法是把“future 何时完成”和“任务何时退出”作为两条关联但独立的链路：前者由 completeOnTimeout 或 orTimeout 负责，后者由取消标记、中断检查、底层客户端超时和资源清理负责。

把结果来源和风险记录下来

超时降级最怕的是“看起来成功，实际上不知道为什么成功”。建议在结果对象中保留 REAL、FALLBACK、TIMEOUT_ERROR 等来源标记，日志至少记录预算、实际耗时、线程池名称和下游调用状态。这样可以区分偶发慢请求、持续容量不足和备用值本身失效。

• 允许降级：用 completeOnTimeout，备用值必须能安全展示。
• 不允许静默降级：用 orTimeout，交给上层统一处理。
• 必须释放资源：检查底层客户端超时、取消信号和 finally 清理。
• 必须防止堆积：为慢任务设置独立线程池、队列上限和监控指标。

复查时只问三件事：调用方是否在预算内返回、后台任务是否有退出路径、备用值是否被清楚标记。三者都成立，超时策略才算完整。

常见问题

completeOnTimeout 会中断正在运行的任务吗？

不会。它改变的是 CompletableFuture 的完成结果；后台 supplier 是否退出，需要任务、客户端和执行器共同配合。

什么时候改用 orTimeout？

当备用值可能掩盖关键失败，或者上层必须统一重试、告警和错误码时，使用异常完成通常更清晰。