CompletableFuture异常需显式处理而非try-catch:handle统一处理结果与异常,exceptionally仅fallback异常且保持类型,whenComplete仅作副作用消费不改变结果。

CompletableFuture 的异常处理不是靠 try-catch 包裹,而是通过专门的异常回调方法主动捕获和响应。核心在于:异常不会自动抛出到调用线程,必须显式注册处理逻辑,否则会静默丢失。
异常不会自动传播,必须显式处理
当 CompletableFuture 执行过程中发生未捕获异常(如 supplyAsync 中抛出 RuntimeException),该异常会被封装进 CompletableFuture 内部,但不会中断主线程,也不会在 get() 之外自动暴露。若未调用 get()、join() 或注册异常处理方法,异常将被忽略。
常见误区是以为链式调用中上一个 stage 抛异常,下一个 thenApply 就会跳过——实际是整个链会短路,后续正常回调不执行,但异常仍需专门捕获。
handle():统一处理结果与异常
handle(BiFunction 是最灵活的兜底方法,无论前序成功或失败,都会执行。它接收两个参数:正常结果(成功时非 null)和异常(失败时非 null),二者必居其一。
立即学习“Java免费学习笔记(深入)”;
- 若前序成功,
throwable为 null,可直接处理结果 - 若前序失败,
result为 null,可检查 throwable 类型并恢复或转换 - 适合做日志记录 + 统一 fallback 返回值
示例:
future.handle((result, ex) -> {
if (ex != null) {
log.error("查询失败", ex);
return "默认值";
}
return result.toUpperCase();
});
exceptionally():仅处理异常,保持类型不变
exceptionally(Function 只在前序异常时触发,返回值类型必须与原始 CompletableFuture 的泛型一致(即提供 fallback 值)。它不能访问正常结果,也不影响成功路径。
- 适合简单兜底:如网络超时返回缓存值、空指针返回空对象
- 若需根据异常类型差异化处理,可在函数内用 instanceof 判断
- 注意:它不处理 CompletionException 包装层,原始异常可通过
getCause()获取
示例:
future.exceptionally(ex -> {
if (ex instanceof TimeoutException) {
return "请求超时,请稍后重试";
} else if (ex.getCause() instanceof IOException) {
return "服务不可用";
}
return "未知错误";
});
whenComplete():只消费,不改变结果
whenComplete(BiConsumer 类似 handle,但不返回新 CompletableFuture,常用于纯副作用操作(如清理资源、发监控告警、打日志)。
- 无法修改结果或异常,也不能中断链式流程
- 适合“无论成败都要做的事”,比如关闭连接、更新状态标记
- 注意:如果在 whenComplete 中抛出新异常,该异常会被丢弃(除非后续有 exceptionally)
示例:
future.whenComplete((result, ex) -> {
if (ex != null) {
metrics.recordFailure(ex.getClass().getSimpleName());
} else {
metrics.recordSuccess();
}
});









