Java CompletableFuture exceptionallyCompose 怎样把异步失败接到备用任务

Java 的 CompletableFuture 主任务失败后，如果备用动作本身也是异步任务，优先用 exceptionallyCompose：它接收异常并返回新的 CompletionStage，让备用阶段的结果继续成为整条链的结果。exceptionally 适合直接返回一个已经准备好的值，不能把一个异步阶段直接当作普通值返回。

本文只讨论把失败接到异步备用任务，不展开重试框架、全局熔断和服务治理。Oracle Java SE 25 API 将 exceptionallyCompose、exceptionallyComposeAsync 标记为 Java 12 起提供的方法。

先看清两种恢复函数的返回类型

我第一次把缓存查询接到远程查询时，最容易写错的是把“启动备用查询”当成“返回备用结果”。两者类型不同：exceptionally 的函数返回 T，exceptionallyCompose 的函数返回 CompletionStage。

// exceptionally：异常发生时直接给出一个已经确定的值
CompletableFuture directFallback = primary
        .exceptionally(error -> {
            // 这里返回的是 String，不是新的异步任务
            return "本地默认值";
        });

// exceptionallyCompose：异常发生时再接入一个异步阶段
CompletableFuture asyncFallback = primary
        .exceptionallyCompose(error -> {
            // 备用查询返回 CompletionStage，链会等待它的结果
            return queryBackupAsync();
        });

如果把 queryBackupAsync() 交给 exceptionally，得到的会是嵌套类型或无法匹配的返回值；如果用 exceptionallyCompose，备用阶段会被“展开”到同一条完成链中。

用 exceptionallyCompose 接上异步备用任务

一个更贴近业务的例子是：先查主数据源，主数据源失败时再查缓存或备用节点。成功路径不进入恢复函数，只有异常完成的阶段才会把异常交给 lambda。

// 主查询失败后，把异常转换成备用查询阶段
static CompletableFuture loadWithBackup() {
    CompletableFuture primary = queryPrimaryAsync();

    return primary.exceptionallyCompose(error -> {
        // 记录主查询异常，但不要在这里阻塞等待备用结果
        logPrimaryFailure(error);
        // 返回新的 CompletionStage，让它的结果接管后续链
        return queryBackupAsync();
    });
}

这里的关键不是“异常后再执行一段代码”，而是恢复函数的返回值仍然是异步阶段。主查询成功时，最终结果就是主查询结果；主查询失败且备用查询成功时，最终结果来自备用查询；备用查询也失败时，整条链仍然以异常完成。

只对允许降级的异常切换

并不是所有错误都适合走备用源。连接暂时失败、读取超时通常可以考虑降级；参数非法、权限拒绝或数据格式错误则不应悄悄换源。恢复函数可以先解包 CompletionException，再按根因做判断。

// 只让可恢复的网络类故障进入备用查询
static CompletableFuture loadWithSelectiveBackup() {
    return queryPrimaryAsync().exceptionallyCompose(error -> {
        // CompletionStage 常把实际原因包在 CompletionException 中
        Throwable cause = unwrapCompletionException(error);
        if (!isRecoverable(cause)) {
            // 不允许降级的异常继续失败，避免掩盖程序或权限问题
            return CompletableFuture.failedFuture(cause);
        }
        // 只有明确允许的故障才启动备用任务
        return queryBackupAsync();
    });
}

static Throwable unwrapCompletionException(Throwable error) {
    // 只剥开常见的完成包装，其他异常原样保留
    if (error instanceof CompletionException && error.getCause() != null) {
        return error.getCause();
    }
    return error;
}

failedFuture 让“不降级”分支仍保持 CompletableFuture 类型。不要在恢复函数里返回 null 来表示失败，否则后续代码很难区分“合法空值”和“异常已被吞掉”。

什么时候需要 exceptionallyComposeAsync

exceptionallyCompose 是非 Async 版本，恢复动作可能由完成主阶段的线程触发。备用查询本身如果只是提交一个异步 IO 任务，通常问题不大；但如果恢复函数包含较重的准备工作，或者团队希望明确隔离恢复任务，就可以选择 exceptionallyComposeAsync 并传入专用执行器。

// 用专用执行器承载备用任务的调度逻辑
static CompletableFuture loadOnFallbackExecutor(Executor fallbackExecutor) {
    return queryPrimaryAsync().exceptionallyComposeAsync(error -> {
        // 这里仍然只返回异步阶段，不要调用 join 阻塞当前线程
        return queryBackupAsync();
    }, fallbackExecutor);
}

不传执行器的 Async 方法使用默认异步执行设施；Oracle 文档说明，默认异步任务使用 ForkJoinPool.commonPool()。如果备用查询有独立的线程池、限流或上下文要求，显式传入执行器更容易观察和控制。

备用任务再次失败时怎样定位

备用任务不是“保证成功”的魔法。它失败时，返回的阶段仍会异常完成，调用方用 whenComplete 或最终的 handle 记录结果即可；不要在恢复函数里立即 join()，否则异步链会退化成阻塞调用。

// 在链尾区分最终成功和备用任务再次失败
loadWithSelectiveBackup().whenComplete((value, error) -> {
    if (error != null) {
        // 记录最终异常，重点保留主故障和备用故障的关联标识
        logFinalFailure(error);
        return;
    }
    // 成功值可能来自主查询，也可能来自备用查询
    logLoadedValue(value);
});

排查时我会按三个问题分层：第一，主阶段是否真的异常完成；第二，异常类型是否被允许降级；第三，备用阶段是否被创建但随后又异常完成。这样可以把“没有进入备用任务”和“进入备用任务但备用失败”分开。

一张表记住选择

最后只记住一个判断：如果异常处理函数返回的是已经算好的 T，用 exceptionally；如果它要返回另一个异步阶段，使用 exceptionallyCompose。成功、降级成功和备用失败三条路径都应在链尾留下可观察的结果。