Java CompletableFuture 异常处理怎么选：exceptionally、handle 与 whenComplete 的流水线边界

订单校验服务通常不是一条直线：先查库存，再做价格计算，最后把结果交给发布门禁。某一步失败后，代码到底应该返回默认值、把结果改成失败对象，还是只记一条日志？在 CompletableFuture 里，exceptionally、handle 和 whenComplete 的差别，正好对应这三种决策。

一条异步流水线里，失败会流向哪里

先用一个常见的业务场景固定讨论边界：loadOrder 返回订单信息，checkStock 返回库存校验结果，最后由 publishGate 决定是否进入后续下单流程。这里的“进入下一步”非常关键，因为异常处理函数会直接改变后续阶段能拿到的执行状态。

CompletableFuture order = loadOrder(orderId);
CompletableFuture checked = order.thenCompose(this::checkStock);

checked.thenAccept(this::publishGate)
       .whenComplete((value, error) -> metrics.record("order-check", error));

如果 checkStock 异常完成，thenAccept 不会收到一个只执行了一半的半成品结果。此时可以在当前调用链上做自动恢复，也可以保留异常状态，把处理决定权交给更上层的业务逻辑。Java SE 21 的官方 API 文档把 CompletableFuture 定义为可显式完成、也可挂接依赖动作的 CompletionStage；异常处理方法的选择，本质上就是定义后续所有依赖动作的输入形态。

什么时候用 exceptionally 做局部兜底

exceptionally 的回调只有在上游任务异常完成时才会运行。它返回的结果和上游是同一个泛型类型，所以特别适合“服务失败时返回一个可接受的默认结果”这类动作，例如库存查询服务暂时不可用时，把商品推荐区标记为空列表，而不是让整页接口直接报错。

CompletableFuture> coupons = loadCoupons(userId)
    .exceptionally(error -> {
        log.warn("coupon service unavailable", error);
        return List.of();
    });

这里返回的空列表不能直接当成“没有符合条件的优惠券”这类业务事实，而是提前预设的降级策略。生产环境的代码最好让结果对象携带 degraded=true 或来源状态，避免把服务故障伪装成正常的空业务数据。如果兜底函数自身执行过程中再次抛出错误，新的阶段仍然会标记为异常完成，不能把这个方法当成自动重试的实现方案。

什么时候用 handle 统一成功与失败

如果调用方不想分别读取正常值和单独捕获异常，而是希望每次调用都得到一个明确的 CheckResult，用 handle 会更顺手。它同时接收正常结果与 Throwable，可以把两条独立的执行路径合并成统一的返回协议。

CompletableFuture result = checkStock(order)
    .handle((stock, error) -> {
        if (error != null) {
            return CheckResult.failed("STOCK_DEPENDENCY", error.getMessage());
        }
        return CheckResult.ok(stock.available());
    });

result.thenAccept(this::publishGate);

这段代码的后续阶段会正常拿到一个 CheckResult，哪怕前面的库存查询环节已经执行失败。它适合业务协议已经把“执行失败”设计成一种合法返回结果的场景，不能把数据库断连、权限校验错误这类必须中断流程的故障全部改成普通结果对象。统一返回值不是降低故障等级的借口。

把 whenComplete 放在观测和清理位置

whenComplete 的核心特点是“仅做观测，不修改主线结果”。它可以记录调用耗时、错误类型、请求标签，或者释放一个和当前阶段绑定的临时资源。正常完成时拿到对应业务结果，异常完成时拿到抛出的原始异常，但主阶段本身的结果和异常传播路径应该完整保留。

CompletableFuture checked = checkStock(order)
    .whenComplete((value, error) -> {
        timer.stop();
        if (error != null) {
            log.error("stock check failed", error);
        }
    });

不要在 whenComplete 里把异常打印出来就认为问题已经处理完了。下游逻辑仍可能因为异常状态跳过正常回调，最终由 join 抛出 CompletionException。如果你确实要改成降级结果，应该明确写出 exceptionally 或 handle，让代码评审时能清晰看到这次状态转换的逻辑。

质量门禁应该检查哪些边界

可以把异常策略当成流水线的门禁配置，而不是最后随便补一行无关日志。下面这张表可以直接放进代码评审检查清单：

测试时至少要覆盖三条路径：上游正常完成、上游异常完成、回调自身抛出异常。尤其要断言 isCompletedExceptionally()、join() 的行为和最终结果字段，而不是只看日志有没有正常输出。

常见问题：异常处理链怎么避免写反

exceptionally 能处理正常结果吗？

不能。上游正常完成时它不会被调用，正常值会直接传给后续阶段。需要同时检查成功与失败场景时，应考虑 handle。

handle 会不会把所有故障都变成成功？

它可以返回一个正常完成的结果，但是否这样做完全取决于业务协议定义。对权限不足、数据损坏、配置错误这类故障，通常应该继续抛出或交给统一错误层接管。

whenComplete 里抛异常会怎样？

观测回调抛出的异常会影响返回的阶段状态，可能覆盖原本的完成状态。日志和资源清理代码要尽量写得可控，必要时在回调内部自行做异常捕获保护。

三种方法可以串在一起吗？

可以，但要按职责先后排列：先用 whenComplete 做执行记录，局部可恢复时再接 exceptionally，需要统一业务协议时再用 handle。不要为了看起来功能完整就把三个方法往每条调用链上都加一遍。

把选择变成一条可执行的判断

只想给同类型结果一个明确的默认值，选 exceptionally；成功和失败都要转成约定好的业务结果，选 handle；只需要埋点指标、打印日志或做资源清理，并且要完整保留原异常，选 whenComplete。先梳理清楚下游必须拿到什么状态，再决定用哪个方法，通常比从方法名倒推行为要稳妥得多。