Java CompletableFuture串联异常与超时的处理方案

Java CompletableFuture 串联多个远程调用时，最容易出问题的地方不是把任务接起来，而是没有为每个异步边界规定失败语义。比较稳妥的做法是：每个阶段单独设置 orTimeout，只在明确的异常类型上使用 exceptionally 做有限降级，最后用 handle 将结果和 Throwable 一起收口。这样超时、业务失败和未知异常不会被一个默认值混成同一种情况。

先把异步链拆成可判断的边界

假设一次下单需要先创建订单，再查询库存，最后计算优惠。三个阶段的耗时和失败处理不同：订单创建失败通常不能静默降级，库存查询超时可以返回“库存待确认”，优惠服务超时则可以暂时使用无优惠结果。若把三者写成一条没有边界的链，末端只能看到一个 CompletionException，排查时很难知道是哪一步出了问题。

先为每个阶段定义三个字段：允许等待多久、哪些异常可以降级、降级后调用方看到什么。这个定义比直接在链尾加一个 exceptionally(ex -> defaultValue) 更重要，因为默认值会掩盖业务失败。

给每个异步边界设置自己的超时

Java 9 起可以使用 orTimeout。它在指定时间内没有完成时，让该 CompletableFuture 以 TimeoutException 异常完成；这个动作控制的是 future 的完成状态，不会自动中断已经在执行的底层网络或阻塞任务。

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

// 每个阶段都带有自己的超时，避免总超时掩盖具体依赖。
CompletableFuture orderStage = CompletableFuture
        .supplyAsync(() -> orderClient.create(command), ioExecutor)
        // 订单创建超时属于不可静默恢复的失败。
        .orTimeout(Duration.ofSeconds(2).toMillis(), TimeUnit.MILLISECONDS);

CompletableFuture inventoryStage = orderStage.thenCompose(order ->
        CompletableFuture
                .supplyAsync(() -> stockClient.reserve(order.sku()), ioExecutor)
                // 库存服务单独设定预算，异常类型保留给后面的收口逻辑。
                .orTimeout(800, TimeUnit.MILLISECONDS));

CompletableFuture result = inventoryStage
        .thenApply(inventory -> Result.success(inventory));

这里使用 thenCompose 是为了把“订单完成后返回的 future”展开成同一条链，而不是得到嵌套的 CompletableFuture>。代码中的 ioExecutor 应是为阻塞型客户端准备的隔离线程池；不要把数据库、HTTP 阻塞调用无条件塞进公共 ForkJoinPool。

exceptionally只处理明确的降级分支

exceptionally 只在上游异常完成时执行，正常完成会把原值继续传下去。它适合库存读取失败后返回“待确认”标记，但不适合把所有异常都改成空对象。至少要先区分包装层，检查 CompletionException 的 cause，再决定是否降级。

import java.util.concurrent.CompletionException;
import java.util.concurrent.TimeoutException;

// 只把库存超时转换为可观察的待确认状态，其他异常继续失败。
CompletableFuture decision = inventoryStage
        .thenApply(InventoryDecision::confirmed)
        .exceptionally(ex -> {
            // join/get 常见的包装层不能替代真正的根因。
            Throwable cause = ex instanceof CompletionException && ex.getCause() != null
                    ? ex.getCause() : ex;
            if (cause instanceof TimeoutException) {
                // 降级值必须携带状态，不能伪装成库存充足。
                return InventoryDecision.pending("库存服务超时");
            }
            // 未识别异常交给末端统一记录和告警。
            throw new CompletionException(cause);
        });

如果降级本身需要再次异步调用，例如访问备用库存源，不要在 exceptionally 里同步阻塞等待；可以使用支持异步恢复的组合方式，并为备用调用再设一个更短的预算。重试也不能无条件进行，连接超时、业务拒绝和参数错误的处理策略不同。

用handle在末端收口并保留失败原因

当调用方需要一个稳定的结果模型，同时还要把失败类型写入日志或指标时，handle 比多个分散的 exceptionally 更适合做最终收口。它会同时收到正常结果和异常对象；成功时异常参数为 null，失败时结果参数通常为空。

import java.util.concurrent.CompletionException;
import java.util.concurrent.TimeoutException;

// 末端统一把成功、超时和其他失败映射为可观测结果。
CompletableFuture apiResult = decision.handle((value, error) -> {
    if (error == null) {
        // 成功结果保留业务数据，状态用于监控维度。
        return ApiResult.ok(value);
    }

    // 先去掉CompletionException包装，避免监控只显示包装类名。
    Throwable cause = error instanceof CompletionException && error.getCause() != null
            ? error.getCause() : error;
    if (cause instanceof TimeoutException) {
        // 超时是可恢复信号，但不能写成成功。
        metrics.count("order.dependency.timeout");
        return ApiResult.degraded("依赖超时");
    }

    // 未知异常继续保留原因，交给上层错误处理器。
    metrics.count("order.dependency.failure");
    return ApiResult.failed(cause.getClass().getSimpleName());
});

这里的 ApiResult.degraded 和 ApiResult.failed 是示例结果模型，重点不在类名，而在于把“是否成功、是否降级、失败原因”分开表达。否则前端看到一个空列表，既无法判断是业务上确实为空，还是依赖超时造成的降级。

线程池、取消和回滚要单独确认

超时 future 后，底层任务可能仍占用连接、线程或锁。如果客户端支持取消，应把取消动作绑定到真实资源；不支持取消时，要把超时后的迟到回调设计成幂等，并在连接池和线程池监控中观察积压。

线上处理可以按下面的清单执行：

回滚时先撤掉新增的重试和降级开关，保留异常指标；不要简单删除 orTimeout 让请求无限等待。这样既能恢复调用链，又不会失去判断依赖变慢的信号。

常见问题

orTimeout会自动停止HTTP请求吗？

不会。它改变的是 CompletableFuture 的完成状态；底层请求是否能中断取决于HTTP客户端、连接池和任务实现。

exceptionally和handle该怎么选？

只处理一个明确异常并返回同类型兜底值时用 exceptionally；需要同时读取成功值、异常原因并统一映射结果时用 handle。

为什么日志里总是CompletionException？

join 或组合阶段常会用 CompletionException 包装根因。记录日志和指标前应检查 getCause()，再按 TimeoutException、业务异常和未知异常分类。

每个阶段都设置超时会不会太复杂？

只要阶段边界对应真实依赖，就比一个总超时更容易排查。阶段预算应小于整体请求预算，并给最终收口和回滚留出时间。

CompletableFuture链的关键不是把异常全部转换成默认结果，而是让每个异步边界都拥有可解释的超时、异常和资源责任。先划分阶段，再设置预算，最后用稳定结果模型收口，线上排查才不会只剩下一条模糊的“异步失败”。