Java中CompletableFuture失败时需解包ExecutionException获取原始异常，推荐用handle()提取cause并封装为BusinessException，或在supplyAsync内提前捕获转换，避免重复包装。
在 Java 中，CompletableFuture 执行失败时抛出的 ExecutionException 是一个包装异常（wrapper），其 getCause() 才是真正触发失败的原始异常。若想将它解包为自定义异常（比如 BusinessException），关键不是“转换”，而是**捕获后提取根本原因，并按需重新抛出或封装**。
使用 handle() 或 whenComplete() 提取根本异常
这两个方法能访问到异常信息，且不会中断链式调用。推荐优先用 handle()，因为它支持返回值，便于统一错误处理逻辑：
handle((result, ex) -> { if (ex != null) { Throwable cause = ex instanceof ExecutionException ? ex.getCause() : ex; // 解包 if (cause instanceof BusinessException) { throw (BusinessException) cause; } else if (cause instanceof RuntimeException) { throw new BusinessException("业务执行异常", cause); } else { throw new BusinessException("未知异常", cause); } } return result; })-
whenComplete()更适合纯副作用处理（如打日志、发告警），不建议在此抛异常，否则可能被忽略；若必须抛，需配合thenCompose等后续操作传递。
在 exceptionally() 中直接解包并返回自定义异常对象
exceptionally() 的参数就是 Throwable，但注意：它**接收的是已被 CompletableFuture 包装过的异常（通常是 ExecutionException 或 CompletionException）**，所以仍需解包：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
- 写法示例：
exceptionally(ex -> { Throwable cause = ex.getCause() != null ? ex.getCause() : ex; return new BusinessException("任务失败", cause); }) - 注意：此方法返回的是替代值（非异常），适用于需要兜底返回默认结果的场景；若想“抛出”自定义异常，则不适合单独使用
exceptionally，应结合handle或外部 try-catch。
统一拦截：用 join() 或 get() 后手动解包
当主动阻塞获取结果时（如 Web 层同步等待），可在外层统一处理：
立即学习“Java免费学习笔记（深入）”；
try { Result r = future.join(); } catch (CompletionException e) { throw unwrapToBusinessException(e); } catch (CancellationException e) { throw new BusinessException("任务已取消", e); }-
unwrapToBusinessException()方法内部判断：若e.getCause()非空且非CompletionException，则递归取getCause()直到获得原始异常；再根据类型决定是否强转或包装。 - 注意：
join()抛CompletionException，get()抛ExecutionException，两者都需getCause()解包。
避免重复包装：提交任务时就用 supplyAsync + 显式 try-catch
最干净的方式是在异步任务体内提前捕获并转换异常，让 CompletableFuture 的完成态直接携带自定义异常：
CompletableFuture.supplyAsync(() -> { try { return doSomething(); } catch (SomeCheckedException e) { throw new BusinessException("业务异常", e); } catch (RuntimeException e) { throw e; } })- 这样下游调用
join()或handle()时，拿到的就是BusinessException本身，无需解包 ——ExecutionException根本不会出现。
