Java CompletableFuture allOf 异常时怎么找到具体失败任务

Java 里用 CompletableFuture.allOf 等待一组并发任务时，join() 抛出的 CompletionException 只能说明聚合结果失败，不能直接告诉你是第几个任务出错。可靠做法是：在每个子任务上先用 handle 保存任务标识、成功值或原始异常，再让 allOf 负责等待，最后遍历这些状态对象生成失败清单。

为什么 allOf 只能告诉你聚合失败

Oracle 的 API 说明中，allOf 会在所有 future 完成后完成；只要其中一个异常完成，返回的 future 也会异常完成，并以 CompletionException 保存原因。但它的正常结果类型是 Void，各 future 的结果不会自动放进聚合对象里。

因此，下面这种写法适合判断“这一批是否成功”，却不适合排障：

List> jobs = submitJobs();
try {
    // 等待整组任务结束；异常只说明聚合失败
    CompletableFuture.allOf(jobs.toArray(CompletableFuture[]::new)).join();
} catch (CompletionException ex) {
    // cause 是某个失败原因，但这里没有任务编号
    System.err.println("批量任务失败: " + ex.getCause());
}

用 handle 保留每个任务的异常

把任务标识和任务 future 放在一起，然后对每一个 future 调用 handle。它无论遇到正常结果还是异常，都会执行回调，可以统一生成一个不会再抛出的 TaskOutcome。

record TaskOutcome(String id, String value, Throwable error) {}

static CompletableFuture observe(String id, CompletableFuture task) {
    return task.handle((value, error) -> {
        // 保留任务标识；不要在这里把原始异常改成普通字符串
        return new TaskOutcome(id, value, unwrap(error));
    });
}

static Throwable unwrap(Throwable error) {
    // join/异步阶段可能多包一层，排障时沿 cause 找到原始异常
    Throwable current = error;
    while (current instanceof CompletionException && current.getCause() != null) {
        current = current.getCause();
    }
    return current;
}

等待全部完成后生成失败清单

状态 future 本身已经把异常转换成了普通结果，所以可以安全地交给 allOf。注意这里的 join 只等待状态收集，不会因为某个原始任务失败而中断。

List> observed = List.of(
    observe("user-101", loadUser("101")),
    observe("user-102", loadUser("102")),
    observe("user-103", loadUser("103"))
);

// 所有状态对象都能正常完成，allOf 只承担等待职责
CompletableFuture.allOf(observed.toArray(CompletableFuture[]::new)).join();
List outcomes = observed.stream().map(CompletableFuture::join).toList();
List failures = outcomes.stream()
    .filter(item -> item.error() != null)
    .toList();

failures.forEach(item -> System.err.println(
    // 输出稳定的任务标识，便于日志、重试和告警关联
    item.id() + " failed: " + item.error()));

如果原始任务可能被取消，unwrap 后得到的可能是 CancellationException。生产代码可以把它单独归类为“取消”，不要和网络异常、业务异常混在同一条重试规则里。重试时也只提交 failures 对应的任务，避免整批重复执行。

常见问题

allOf 的 CompletionException 是不是失败任务的完整列表？

不是。它代表聚合 future 的异常完成，通常只暴露一个原因；完整列表必须从每个子任务的状态中收集。

为什么不用 exceptionally 记录失败？

exceptionally 只在异常完成时计算替代值；如果还要保留成功值、任务编号和异常对象，handle 的输入更完整。

可以在 allOf 抛异常后再遍历子任务吗？

可以，但要确认所有子任务已经结束，并逐项读取它们的状态；不要对失败任务直接无保护地调用 join，否则会再次抛异常。