结论先行:CompletableFuture 解决的是「多个异步任务的依赖编排与结果聚合」,核心 API 就四组:创建、转换、组合、异常兜底。用对的前提只有一个——所有 async 方法显式传入自己的线程池,默认的 ForkJoinPool.commonPool 只适合纯 CPU 计算,IO 任务用它等于埋雷。
从串行到编排
商品详情页要调三个下游:商品信息、价格、库存。串行耗时是三者之和,编排后接近最大者:
// 实际项目请自定义 ThreadFactory 命名线程,此处从简
ExecutorService pool = new ThreadPoolExecutor(8, 16, 60, TimeUnit.SECONDS,
new ArrayBlockingQueue<>(256));
CompletableFuture<ItemInfo> itemF =
CompletableFuture.supplyAsync(() -> itemService.query(sku), pool);
CompletableFuture<Price> priceF =
CompletableFuture.supplyAsync(() -> priceService.query(sku), pool);
CompletableFuture<Stock> stockF =
CompletableFuture.supplyAsync(() -> stockService.query(sku), pool);
Detail detail = itemF
.thenCombine(priceF, (item, price) -> new Detail(item, price))
.thenCombine(stockF, Detail::fillStock)
.orTimeout(3, TimeUnit.SECONDS) // JDK 9+ 超时控制
.exceptionally(ex -> Detail.fallback(sku)) // 降级兜底
.join();
任何一个下游挂了不影响整体返回,exceptionally 提供降级值,超时用 orTimeout 控制。这是编排相对「手动开三个线程再 join」最大的工程价值:异常处理和聚合逻辑写在数据流上,而不是散落在各线程的回调里。补充一个易错点:join 抛出的是非受检的 CompletionException,触发条件不止业务异常,超时(TimeoutException 包装在内)也会走到这里,降级逻辑要对异常类型做区分——下游全挂时整体降级,个别字段缺失时只降级对应字段,两种粒度分开写。
创建 API 还有两个变体要区分:runAsync 无返回值(Runnable),supplyAsync 有返回值(Supplier);complete(v) 可以从外部线程手动完成一个 Future(提前注入结果或失败),做「最快返回者获胜」的竞速时很有用——两个等价查询并行发出,谁先完成谁 complete,另一个直接放弃。
编排的粒度也要控制:一条链上的异步步骤与分支会随业务增长而膨胀,超过五六步可读性就开始崩塌。真正的复杂编排应拆成「子编排」各自聚合后再组合,而不是把十几个 Future 链在同一条表达式里——编排代码的可读性同样是工程价值的一部分,拆分还有个附带收益:子编排可以单独压测与监控。
thenApply、thenCompose 与 Async 后缀
thenApply 接收转换函数返回普通值,thenCompose 接收返回 CompletableFuture 的函数。需要在一个异步步骤里再发起异步调用(先查订单 ID 再查订单详情)时用 thenCompose,否则会得到 CompletableFuture<CompletableFuture<T>> 这种嵌套类型。与 Stream 的 map/flatMap 同构,记一个等于记两个。Async 后缀决定「下一步在哪个线程跑」:不带后缀的方法(如 thenApply)通常由「上一个任务完成的线程」或调用方线程执行回调;带 Async 的(如 thenApplyAsync)把回调提交到指定线程池。涉及慢 IO 的回调一律带 Async 并显式传池,否则回调会占住上游的执行线程,拖慢整条链。常用方法能力对照:
| 方法 | 回调函数形态 | 结果类型 | 典型用途 |
|---|---|---|---|
| thenApply | 返回普通值 | CompletableFuture | 同步转换上游结果 |
| thenCompose | 返回 CompletableFuture | CompletableFuture | 串联两段异步调用 |
| thenCombine | 两个 Future 的二元函数 | CompletableFuture | 汇聚两个并行结果 |
| allOf | 变长 Future 数组 | CompletableFuture | 等待一批任务全部完成 |
| exceptionally | 异常转默认值 | CompletableFuture | 失败降级 |
| completeOnTimeout | 超时填默认值 | CompletableFuture | 超时降级(JDK 9+) |
回调家族按「要不要结果」分三档:thenApply 消费并返回新值、thenAccept 消费不返回、thenRun 不消费不返回;再叠加 Async 变体就是一张 3×2 的方法矩阵。读源码或选 API 时按矩阵对号入座,不会迷路。
异常传播还有一个特性要理解:编排链上任何一环抛异常,整条链都会以异常完成,后续的非异常处理回调直接跳过——不是「跳过出错那步继续往下」,这点与同步代码的 try-catch 直觉不同。想把某一步的失败隔离在链内,在该步后面立刻接 exceptionally 或 handle 把结果修回来,而不是指望链尾统一兜底。
线程池必须显式传入
所有 supplyAsync/runAsync 重载都有带 Executor 的版本,不传池就落进 ForkJoinPool.commonPool——它是全 JVM 共享的,容量约等于 CPU 核数减一。在 Web 服务里把慢 IO 任务投进 commonPool,高峰期公共池被占满,服务里所有依赖它的并行流、公共编排全部排队:
// 错误写法:不传池,任务落进全局共享的 commonPool
CompletableFuture<Price> priceF =
CompletableFuture.supplyAsync(() -> priceService.query(sku)); // 危险
// 正确写法:按下游/业务隔离线程池,线程有名字,队列有界
ExecutorService pricePool = new ThreadPoolExecutor(
8, 16, 60L, TimeUnit.SECONDS,
new ArrayBlockingQueue<>(256),
namedFactory("price-query"), // jstack 可定位
new ThreadPoolExecutor.CallerRunsPolicy());
CompletableFuture<Price> priceF =
CompletableFuture.supplyAsync(() -> priceService.query(sku), pricePool);
隔离的粒度按下游重要性决定:核心下游独立线程池,非核心共享一个低优先级池,任何一组下游故障都不会拖垮其他链路。这是异步编排比「更快」更重要的价值——故障隔离的边界。
默认 commonPool 还有参数不可控的问题:它的并行度只能全局调整(java.util.concurrent.ForkJoinPool.common.parallelism 系统属性),影响整个 JVM。而业务线程池的并行度、队列、拒绝策略都可以按下游定制——这是必须显式传池的根本原因。
三个实战纪律
一是超时必须设:下游卡死会让整个编排悬挂,JDK 9+ 用 orTimeout,再接 completeOnTimeout(默认值, 超时时间, 单位) 可以直接给超时的任务填降级值。二是批量聚合用 allOf:
List<CompletableFuture<Order>> futures = ids.stream()
.map(id -> CompletableFuture
.supplyAsync(() -> orderService.query(id), pool)
.orTimeout(2, TimeUnit.SECONDS)) // 每个任务独立超时
.collect(Collectors.toList());
CompletableFuture.allOf(futures).join(); // 等全部完成
List<Order> orders = futures.stream()
.map(CompletableFuture::join) // 再逐个取结果
.collect(Collectors.toList());
allOf 本身不携带结果值,「先 allOf 等齐、再逐个 join」是标准套路。部分失败可容忍的批量场景,把 join 包进 try-catch,失败的槽位填降级值,不要让一个下游拖垮整批。三是别在异步链里写阻塞调用和长临界区的 synchronized——异步代码里一旦阻塞,线程池吞吐假死,表现为线程数正常但任务堆积,排查时 jstack 会看到大量线程 WAITING 在业务代码上。
超时还有一个组合技巧:orTimeout 超时后 Future 以 TimeoutException 异常完成,但真正的任务线程还在跑——它不会中断底层任务。超时只是「放弃等待」,不是「终止执行」,要真正终止需要任务自己响应取消(检查中断标志或改用支持取消的方案),理解这一点才能正确设计补偿逻辑。
批量场景还有两个细节:allOf 的 join 抛出的是第一个完成的异常(不是全部),要收集所有失败仍需逐个 join;任务量极大时分批提交,避免一次性把队列塞满把内存顶爆。
生产案例
某次大促,商品详情页接口整体超时告警。排查发现价格服务当天响应时间抬升,而编排代码里 supplyAsync 没有设超时:每个请求的三个 Future 中价格那个一直悬挂,编排线程池被逐步占满,后续请求连提交都进不去,详情页从「慢」滑向「不可用」。恢复动作是先把编排池的队列与线程数临时上调顶过峰值,随后完成根治:所有下游调用补 orTimeout 与 completeOnTimeout 降级值;价格、库存、商品三个下游各自独立线程池;活跃线程数与队列水位接入告警。下次同类故障的影响范围被限制在价格一个字段上——降级值顶上,其余字段正常返回。这个案例的关键认知:CompletableFuture 的超时不是「锦上添花的参数」,是编排可用性的前提;没有超时的异步链,等于把下游的故障无差别传导给自己。度量上再补一条:给编排链路增加「每步耗时」的结构化日志,故障时能直接看到哪一环触发超时降级,不再靠上下游时间戳对表,同时把降级路径纳入常规压测场景。
检查清单
- 所有 supplyAsync/runAsync 显式传线程池,禁止裸用 commonPool
- 按下游重要性隔离线程池,核心与非核心不共用
- 每段异步链设 orTimeout,超时配合 completeOnTimeout 给降级值
- 串联异步调用用 thenCompose,避免嵌套泛型类型
- 批量聚合先 allOf 等齐、再逐个 join,部分失败单独降级
- 异步回调里禁止阻塞调用与长临界区 synchronized
- 编排池接入活跃线程数、队列水位监控
- join 抛出的 CompletionException 按异常类型区分处理