Java CompletableFuture whenComplete 如何记录异常而不改变结果

我在给异步订单请求补日志时，最先想到的是把记录代码塞进 thenApply，结果失败分支根本没有日志。换成 whenComplete 后，成功值和异常都能在同一个回调里看到，而且返回的新阶段默认继续保留上游结果。

关键是把它当“观察点”，不要把它当异常转换器：记录动作正常返回时，成功仍是成功、失败仍是失败；如果记录器自己抛错，返回阶段才可能受到影响。

whenComplete 为什么能记录异常却不改结果

whenComplete 接收一个 BiConsumer super T, ? super Throwable>。正常完成时，结果参数有值、异常参数为 null；异常完成时，结果通常为 null、异常参数携带失败原因。回调执行完后，返回的 CompletionStage 默认复制原阶段的完成语义。

这和 handle 的职责不同。handle 会把结果或异常转换成新的值，适合“失败时返回兜底对象”；whenComplete 只做旁路观察，后续链仍应看到原来的成功值或异常。

把成功和失败放进同一个记录点

下面的写法把请求编号带进回调，只记录必要摘要。日志方法本身不参与业务转换，因此后面的 thenApply 仍按原结果工作。

CompletableFuture checked = loadOrder(orderId)
    .whenComplete((order, error) -> {
        // 正常分支只记录结果摘要，避免把完整敏感对象写入日志
        if (error == null) {
            logger.info("order loaded, requestId={}, status={}", requestId, order.status());
            return;
        }
        // 异常分支保留 Throwable，便于定位 CompletionException 的 cause
        logger.warn("order load failed, requestId={}", requestId, error);
    });

CompletableFuture status = checked.thenApply(order -> {
    // 这里仍然只能收到上游成功值；失败会沿链传播到消费点
    return order.status();
});

如果只关心成功或失败，也可以在回调里分别维护计数，但不要在这里把异常包装成“成功”。这正是观察点和转换点的边界。

回调抛错时，结果为什么可能变化

官方 API 对这个细节有明确规则：上游正常而回调抛异常时，返回阶段会以回调异常异常完成；上游已经异常时，即使回调再抛异常，返回阶段仍以原阶段的异常为主。因此记录器应尽量短小、无阻塞，并对日志系统的偶发故障做隔离。

whenCompleteAsync 只改变回调使用的执行设施，不改变“观察而不转换”的语义。默认异步设施不适合所有场景；若记录动作会访问慢速外部系统，建议明确传入专用执行器，避免挤占业务线程池。

用最小检查确认业务结果没有被改写

验证时不要只看日志是否出现，还要检查 whenComplete 返回的阶段：

try {
    // join 只用于示例验证：失败时会以 CompletionException 暴露原因
    String value = status.join();
    assert value != null;
} catch (CompletionException ex) {
    // 验证异常仍抵达消费点，而不是被记录回调静默吞掉
    logger.debug("completion kept exceptional, cause={}", ex.getCause());
}

我的经验是：日志、指标、链路标记放 whenComplete；需要把异常变成业务返回值时改用 handle；需要只处理异常时用 exceptionally。三者混在一起，最容易让“记录”悄悄变成“改结果”。

相关问题

whenComplete 会吞掉异常吗？

不会。只要回调正常返回，原阶段的异常会继续传播；需要兜底值时应显式使用 handle 或 exceptionally。

whenComplete 和 thenAccept 有什么区别？

thenAccept 只在上游成功时执行，拿不到失败分支；whenComplete 同时观察成功值和 Throwable。

记录日志应该用 whenCompleteAsync 吗？

纯内存、很短的记录可以同步执行；如果会阻塞或访问外部日志系统，使用明确的异步执行器，并控制队列和关闭策略。