CompletableFuture异常不会自动抛出或中断链式调用，必须显式通过exceptionally、handle或whenComplete捕获，否则静默丢失；未处理异常仅在get/join时包装抛出，线上易致无日志无告警；allOf等组合方法不传播异常，需手动处理。
CompletableFuture 的报错处理核心在于：异常不会自动抛出，必须显式捕获或传播，否则会静默丢失。
异常不会自动中断链式调用
Unlike traditional synchronous code, when a stage in a CompletableFuture chain throws an exception, it doesn’t stop the chain — instead, the exception is stored internally and the next stage (if using thenApply, thenAccept, etc.) won’t execute. But if you use exceptionally, handle, or whenComplete, you can catch and react.
-
exceptionally(Function<throwable t>)</throwable>：只在前一阶段异常时触发，返回替代结果（类型需一致），类似 try-catch 中的 catch 块 -
handle(BiFunction<t throwable r>)</t>：无论成功或失败都会执行，第二个参数是可能为 null 的异常，适合统一兜底或日志记录 -
whenComplete(BiConsumer<t throwable>)</t>：和 handle 类似，但不改变结果值，适合做副作用（如清理、打日志）
不要忽略未处理的异常
如果一个 CompletableFuture 完成时带有异常，但后续没接 exceptionally、handle 或 get()，异常会一直“沉睡”。直到你调用 get() 或 join() 时才抛出 —— 此时是 ExecutionException（get）或 CompletionException（join），原始异常被包装在 cause 中。
- 线上服务中常见问题：异步任务失败但无日志、无告警，因为没人调用 get/join，也没写 exceptionally
- 建议每个异步链至少有一个
exceptionally或handle，哪怕只是打日志 - 测试时别只看是否“跑通”，要主动构造异常场景验证错误路径
组合多个 CompletableFuture 时的异常传播
像 allOf 和 anyOf 这类静态方法本身不处理异常：
立即学习“Java免费学习笔记（深入）”；
-
CompletableFuture.allOf(f1, f2, f3)返回的 CompletableFuture 在任意子任务异常时仍会“完成”，但不会暴露哪个失败；你需要手动检查各 future 的isCompletedExceptionally()或调用getNow(null)+get()捕获 - 更稳妥的方式：用
allOf后接thenApply，再对每个原始 future 调用join()（会立即抛异常），或改用collect-style 手动聚合（如future1.thenCombine(future2, ...)） - 推荐封装工具方法，比如
allOfWithExceptionPropagation(...)，内部对每个 future 做handle((r, t) -> { if (t != null) throw new CompletionException(t); return r; })
常见误用与修复示例
下面这段代码看似正常，实则隐患很大：
❌ 错误写法（异常被吞）：CompletableFuture.supplyAsync(() -> { throw new RuntimeException("boom"); })
.thenApply(s -> s.length()); // 这行根本不会执行
// 后续无任何异常处理，异常静默丢失
✅ 推荐写法（显式兜底）：
CompletableFuture.supplyAsync(() -> {
if (Math.random() > 0.5) throw new RuntimeException("boom");
return "ok";
})
.exceptionally(t -> {
log.error("Async task failed", t);
return "fallback"; // 类型匹配
})
.thenAccept(System.out::println);
基本上就这些。关键不是“怎么写更炫”，而是“让异常不隐身”——每条异步链，都该有明确的错误归属和响应动作。
