17370845950

CompletableFuture 是可组合的异步计算容器，核心是解耦任务提交与结果消费、支持链式编排；它不是线程池或回调管理器，也不等同于升级版 Future，滥用 get/join 会丧失组合优势。

CompletableFuture 是什么，不是什么

它不是线程池，也不是回调管理器，而是一个可组合的异步计算容器。它的核心价值在于把「任务提交」和「结果消费」解耦，并支持链式编排——比如 thenApply、thenCompose、whenComplete 这些方法，让多个异步操作能像写同步代码一样自然衔接。

常见误解是把它当 Future 的简单升级版：其实 Future.get() 会阻塞，而 CompletableFuture 的真正能力在「不阻塞的前提下定义依赖关系」。一旦你用 get() 或 join() 等待结果，就等于放弃了它的组合优势。

什么时候该用 CompletableFuture，而不是直接 new Thread 或 ExecutorService.submit

当你需要以下任意一种能力时，CompletableFuture 才真正必要：

• 多个异步任务有先后/并行/条件依赖（例如：查用户 → 查订单 → 合并数据 → 发通知）
• 需要对异常做细粒度处理（handle 或 exceptionally 可单独捕获某一步失败）
• 要统一超时控制（orTimeout + completeOnTimeout 比手动 Future.get(3, SECONDS) 更可控）
• 需与其他异步生态对接（如 Spring WebFlux 的 Mono、Vert.x 的 Promise）

如果只是“扔一个任务去后台跑”，用 executor.submit(Runnable) 更轻量；强行套 CompletableFuture.runAsync 反而增加无谓的对象开销。

容易踩的坑：线程上下文丢失、异常静默、默认线程池陷阱

CompletableFuture 默认使用 ForkJoinPool.commonPool()，这个线程池不支持自定义 ThreadLocal 绑定（比如日志 traceId、Spring Security 上下文），也不适合 IO 密集型任务（因为 commonPool 默认并行度 = CPU 核心数 - 1）。

正确做法是显式传入专用线程池：

ExecutorService ioPool = Executors.newCachedThreadPool();
CompletableFuture.supplyAsync(() -> apiCall(), ioPool);

另外，thenAccept、thenApply 这类方法内部抛异常会直接“消失”——不会中断链路，也不会打印日志。必须用 exceptionally 或 handle 显式兜底：

CompletableFuture.supplyAsync(() -> riskyOperation())
    .thenApply(result -> process(result))
    .exceptionally(ex -> {
        log.error("处理失败", ex);
        return fallbackValue();
    });

还有个隐蔽问题：thenCompose 和 thenCombine 参数类型不匹配时编译报错不明显，容易误写成 thenApply 导致嵌套 CompletableFuture（即 CompletableFuture>）。

与 Reactor/Mono 对比：别硬套响应式术语

有人试图把 CompletableFuture 当作“Java 版 Mono”来用，比如频繁调用 toMono().flatMap(...).block()，这反而破坏了异步流控。二者定位不同：

• CompletableFuture 是单次计算结果的管道，适合“请求-响应”类场景（HTTP 调用、DB 查询）
• Mono/Flux 是响应式流，天然支持背压、取消、多事件（如 WebSocket 流、文件分块上传）

混用时注意：从 CompletableFuture 转 Mono 应用 Mono.fromFuture(cf)，而非 Mono.just(cf).flatMap(f -> ...) —— 后者会把 future 对象本身当作数据发射出去。

复杂编排逻辑里，thenCompose 的扁平化语义和 flatMap 最接近，但线程调度模型完全不同：前者依赖你传入的 Executor，后者由 Scheduler 控制。