CompletableFuture 组合独立任务：allOf 结果汇总与失败归属

把订单、库存、优惠三个独立查询交给 CompletableFuture 后，很多代码会停在 CompletableFuture.allOf(...).join()：全部成功时看起来没问题，但只要一个任务失败，外层只收到 CompletionException，而 allOf 自己又没有结果列表。要同时拿到每项结果和失败归属，关键是把 allOf 当成“完成屏障”，并在进入屏障前给每个任务附上名称和异常转换。

Oracle CompletableFuture API：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/CompletableFuture.html

最稳妥的组合方式分两类：要求全成全败时，直接等待 allOf，再逐项 join()；允许部分成功时，先对每个 Future 使用 handle()，把成功值或根异常转换成统一的 TaskResult，然后再 allOf。第二种写法不会丢失失败任务名。

症状：allOf 完成了，却没有结果列表

下面是常见的聚合写法。三个任务彼此独立，可以同时提交：

ExecutorService pool = Executors.newFixedThreadPool(3);

CompletableFuture orderFuture = CompletableFuture.supplyAsync(
    () -> loadOrder("O-42"),
    pool
);
CompletableFuture stockFuture = CompletableFuture.supplyAsync(
    () -> loadStock("SKU-7"),
    pool
);
CompletableFuture couponFuture = CompletableFuture.supplyAsync(
    () -> loadCoupon("U-9"),
    pool
);

// 中文说明：allOf 只表示三个 Future 都已完成，返回类型是 Void
CompletableFuture barrier = CompletableFuture.allOf(
    orderFuture,
    stockFuture,
    couponFuture
);

Oracle 文档明确说明，allOf 返回的是 CompletableFuture。它不会把子任务的值自动塞进数组或列表，实际结果仍保存在 orderFuture、stockFuture 和 couponFuture 中。

这不是 API 缺陷，而是类型设计的取舍：传入的 Future 可以拥有不同结果类型，allOf 无法构造一个统一泛型列表。它只负责表达“所有任务都结束了”这一事实。

全部成功时：屏障之后再逐项读取

如果业务要求三项必须全部成功，最小写法是让屏障先完成，再在后续阶段读取每个 Future：

CompletableFuture> combined = barrier.thenApply(ignored -> {
    // 中文说明：进入这里时所有子任务都已完成，join 不会再次等待未完成任务
    return Arrays.asList(
        orderFuture.join(),
        stockFuture.join(),
        couponFuture.join()
    );
});

try {
    List values = combined.join();
    values.forEach(System.out::println);
} finally {
    // 中文说明：自建线程池由创建方负责关闭
    pool.shutdown();
}

这段代码适合“缺一项就不能继续”的场景。任一子任务异常完成时，barrier 也会异常完成，thenApply 不会执行，最外层 join() 抛出未检查的 CompletionException。

一个重要判断是：allOf 并不把失败任务从其他任务中取消，也不是“第一个异常立刻返回”的失败快速开关。它的完成条件仍然是所有传入 Future 都完成；只是最终状态会因为至少一个异常而变成异常完成。

证据：为什么外层异常看不出失败任务名

直接组合原始 Future 时，屏障只承诺“如果任一子任务异常，返回的 Future 也异常完成，并由 CompletionException 持有异常原因”。它不承诺把全部异常按任务名组成报告。

假设库存查询和优惠查询都失败，捕获 combined.join() 的异常只能得到聚合阶段暴露的一条异常链；想知道每个任务发生了什么，仍需回到各自 Future。下面的检查方法只适用于屏障已经完成之后：

try {
    barrier.join();
} catch (CompletionException aggregateError) {
    // 中文说明：allOf 的异常只说明至少一个子任务失败
    System.err.println("聚合失败: " + aggregateError.getCause());
}

List> originals = Arrays.asList(
    orderFuture,
    stockFuture,
    couponFuture
);

for (CompletableFuture future : originals) {
    Throwable error = future.handle((value, ex) -> ex).join();
    if (error != null) {
        // 中文说明：逐项检查能看到异常，但没有任务名仍难定位业务来源
        System.err.println(unwrap(error).getMessage());
    }
}

这里暴露了真正的问题：只保存一组 Future，最多能通过下标猜任务身份。一旦任务由动态列表生成、顺序变化或结果类型相同，日志很容易失去归属信息。修复应当从创建任务时开始，而不是异常发生后再反推。

修复失败归属：每个任务先转换成 TaskResult

先定义一个统一结果模型，同时保存任务名、成功值和异常。示例使用普通类，便于兼容仍在使用 Java 8 或 Java 11 的项目：

public final class TaskResult {
    private final String taskName;
    private final String value;
    private final Throwable error;

    private TaskResult(String taskName, String value, Throwable error) {
        this.taskName = taskName;
        this.value = value;
        this.error = error;
    }

    public static TaskResult success(String taskName, String value) {
        // 中文说明：成功结果只保存值，不伪造异常
        return new TaskResult(taskName, value, null);
    }

    public static TaskResult failure(String taskName, Throwable error) {
        // 中文说明：失败结果保留根异常，值保持为空
        return new TaskResult(taskName, null, error);
    }

    public boolean succeeded() {
        return error == null;
    }

    public String getTaskName() {
        return taskName;
    }

    public String getValue() {
        return value;
    }

    public Throwable getError() {
        return error;
    }
}

然后在每个任务创建时立刻附上名称，并用 handle() 把正常和异常完成都转换成 TaskResult：

static CompletableFuture tracked(
    String taskName,
    Supplier supplier,
    Executor executor
) {
    return CompletableFuture
        .supplyAsync(supplier, executor)
        .handle((value, error) -> {
            // 中文说明：handle 同时接收正常值和异常，因此转换后的 Future 正常完成
            if (error == null) {
                return TaskResult.success(taskName, value);
            }
            return TaskResult.failure(taskName, unwrap(error));
        });
}

static Throwable unwrap(Throwable error) {
    // 中文说明：去掉 CompletionException 包装，保留真正业务根因
    if (error instanceof CompletionException && error.getCause() != null) {
        return error.getCause();
    }
    return error;
}

因为每个 tracked Future 都会正常完成并产出 TaskResult，后续 allOf 不会再因业务异常而异常完成。失败没有被忽略，而是从“控制流异常”转换为“可汇总的数据”。

完整汇总：同时保留成功项和失败项

把三个任务都通过 tracked() 创建，再统一等待并收集：

ExecutorService pool = Executors.newFixedThreadPool(3);

List> tasks = Arrays.asList(
    tracked("order", () -> loadOrder("O-42"), pool),
    tracked("stock", () -> loadStock("SKU-7"), pool),
    tracked("coupon", () -> loadCoupon("U-9"), pool)
);

CompletableFuture barrier = CompletableFuture.allOf(
    tasks.toArray(new CompletableFuture>[0])
);

try {
    List results = barrier.thenApply(ignored ->
        tasks.stream()
            // 中文说明：屏障完成后逐项读取统一结果对象
            .map(CompletableFuture::join)
            .collect(Collectors.toList())
    ).join();

    List failures = results.stream()
        .filter(result -> !result.succeeded())
        .collect(Collectors.toList());

    for (TaskResult failure : failures) {
        // 中文说明：日志同时包含任务名和底层异常类型，失败归属明确
        System.err.printf(
            "task=%s, error=%s, message=%s%n",
            failure.getTaskName(),
            failure.getError().getClass().getSimpleName(),
            failure.getError().getMessage()
        );
    }
} finally {
    // 中文说明：服务长期复用时应由生命周期组件统一关闭线程池
    pool.shutdown();
}

现在即使库存失败、订单成功、优惠成功，结果列表仍然完整。调用方可以决定返回降级页面、只隐藏库存相关按钮、重试失败任务，或者把 failures 重新组合成业务异常。

反向验证：不要把异常恢复用错地方

全成全败时不要吞异常

如果三项缺一不可，就不应把每个错误都转换成可继续结果。保留原始 Future，让 allOf 异常完成，再在最外层统一失败，语义更直接。handle 方案适合需要完整报告或允许部分成功的场景。

whenComplete 适合观察，不适合改结果

whenComplete 能同时看到值和异常，但返回阶段通常保留原来的完成结果，适合日志、指标和清理。需要把异常转换成 TaskResult 时，应使用 handle；只为异常提供默认值时，可以使用 exceptionally。

join 与 get 的异常包装不同

join() 在异常完成时抛出未检查的 CompletionException；get() 使用受检查的 ExecutionException，并且还要求处理 InterruptedException。在流式聚合代码中 join() 更简洁，但仍应在边界处提取并记录根因。

allOf 不替你选择线程池

不传 Executor 的 supplyAsync 通常使用公共异步执行设施。数据库、远程 HTTP 和高延迟任务最好使用容量、队列和拒绝策略明确的专用线程池，避免与其他并行任务互相拖累。线程数应根据阻塞比例、下游容量和服务限流设计，不能机械等于任务数。

最终检查清单

1. 多个任务是否真正独立，能否安全并行执行。
2. 是否把 allOf 只当作完成屏障，而不是结果容器。
3. 全部成功场景是否在屏障后逐项 join()。
4. 部分成功场景是否在创建任务时就附上稳定的 taskName。
5. 是否用 handle 统一成功值和失败根因，并避免仅凭下标猜任务身份。
6. 是否明确区分 whenComplete 的观察语义与 handle 的转换语义。
7. 线程池是否与阻塞型任务匹配，并由生命周期组件关闭。
8. 是否为外部调用设置超时、取消或降级策略，避免无限等待。

CompletableFuture.allOf 最适合做屏障，不适合做报告。把“何时全部结束”和“每项结果是什么”拆成两层后，代码会清晰很多：屏障负责完成条件，TaskResult 负责结果与失败归属，业务层再决定全成全败还是接受部分成功。

相关问题

allOf 会在第一个任务失败时立刻结束吗？
不会把其他任务自动取消。返回的 Future 要在所有传入 Future 完成后才完成；只要任一任务异常，最终状态就是异常完成。

为什么 allOf 返回 CompletableFuture？
因为输入 Future 可以拥有不同的结果类型，allOf 只表达“全部完成”，结果仍需从各子 Future 获取。

handle 会不会把异常吞掉？
它会把异常转换为新的返回值。示例将异常明确保存到 TaskResult.error，所以没有丢失；如果业务要求失败传播，就不要转换，或在汇总后重新抛出。

如何给整个组合任务设置超时？
可以在屏障或组合 Future 上使用 orTimeout，同时仍要考虑底层任务能否被取消，以及超时后线程和连接如何释放。

参考资料

• CompletableFuture API：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/CompletableFuture.html
• CompletionStage API：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/CompletionStage.html
• ExecutorService API：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/ExecutorService.html