CompletableFuture 异常阶段怎么配置或排查

CompletableFuture 的异常处理，关键不是在链尾随手补一个 exceptionally，而是先确认异常在哪个阶段产生，再决定是记录、转换结果，还是启动异步降级。whenComplete 适合观察，handle 适合同时处理成功和失败，exceptionally 适合同步兜底，exceptionallyCompose 适合把失败接到另一条异步链上。

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

先固定异常发生的阶段

排查时先把链拆成“来源、业务转换、观察点、恢复点”四个位置。下面的代码只展示结构：loadProfile() 或 normalize() 任一处抛错，都会让当前阶段异常完成；whenComplete 能拿到结果和异常，但不会把异常自动变成成功值。

CompletableFuture chain = CompletableFuture
    .supplyAsync(() -> {
        // 这里代表可能失败的远程调用或 IO 操作
        return loadProfile();
    })
    .thenApply(profile -> {
        // 业务转换抛错，也会进入后续异常分支
        return normalize(profile);
    })
    .whenComplete((value, error) -> {
        // 观察阶段只记录，不把失败伪装成成功
        if (error != null) {
            System.err.println("profile stage failed: " + error);
        }
    });

CompletableFuture result = chain.exceptionally(error -> {
    // 只有异常完成时才提供同步兜底值
    return "anonymous";
});

这里有一个容易忽略的点：每个阶段方法都会返回新的 CompletionStage。若只调用 chain.exceptionally(...) 却不保存返回值，原来的 chain 仍然是异常状态，调用方自然看不到兜底结果。

按目标选择异常阶段方法

四个方法的区别可以压缩成一张选择表。先问自己“我要不要改变最终值”，再决定方法：

handle 的回调会同时收到 value 和 Throwable，因此适合把成功和失败统一封装；但如果只是打日志，不要用它把失败转换成一个看似正常的空对象。exceptionallyCompose 从 Java 12 起提供，旧版本可用 handle 配合 thenCompose 表达同类结构。

CompletableFuture recovered = loadAsync()
    .exceptionallyCompose(error -> {
        // 异常时切换到异步缓存，缓存失败仍然继续暴露异常
        return loadFromCacheAsync();
    });

检查线程池与异常包装

带 Async 的方法如果没有显式传入执行器，默认使用 ForkJoinPool.commonPool()；阻塞式日志、远程补偿或数据库访问不要无意间挤进这个公共池。排查时在观察回调中记录阶段名和线程名，并优先传入业务自己的 Executor。

调用边界也会改变你看到的异常形状：join() 抛出未检查的 CompletionException，get() 则常见 ExecutionException。它们通常只是包装层，日志应继续打印根因。

try {
    // join 适合已经完成或由上层统一处理的边界
    return future.join();
} catch (CompletionException ex) {
    // 继续取根因，避免只记录包装类型
    Throwable cause = ex.getCause();
    System.err.println("root cause: " + (cause == null ? ex : cause));
    throw ex;
}

用清单收敛异常排查

• 异常是来源方法抛出的，还是某个 thenApply/thenCompose 回调抛出的？
• 恢复方法是否挂在真正异常的阶段之后，并且接住了返回的新 Future？
• 需要记录就用 whenComplete，需要改变结果才用 handle 或 exceptionally。
• 异步降级是否可能再次失败？若会，必须让这条失败链继续可见。
• 最终边界是否正确解开了 CompletionException 或 ExecutionException？

常见问题

为什么 exceptionally 没有执行？

它只在前一阶段异常完成时触发；如果异常发生在它后面，或者前面已经被 handle 转成成功值，它都不会再次介入。

whenComplete 能返回兜底数据吗？

不能把它当成兜底回调。它主要保持原完成结果并执行观察动作，需要替代值时改用 exceptionally 或 handle。

为什么日志里只有 CompletionException？

这是 join 的异常包装。沿着 getCause() 查看底层异常，并在每个关键阶段记录阶段名，通常就能定位真正的抛错位置。