应优先用thenCompose()串异步操作、thenApply()做同步转换；异常处理选handle()兜底或exceptionally()重试；IO操作必须指定自定义线程池；链式调用中严禁使用join()/get()。
CompletableFuture.thenApply() 和 thenCompose() 到底该用哪个
链式调用卡住、结果类型错乱、异步变同步——八成是混用了 thenApply() 和 thenCompose()。
thenApply() 是“同步转换”，输入一个值，返回一个新值（哪怕你返回的是 CompletableFuture，它也会被包进一层）；thenCompose() 才是“扁平展开”，专门用来接另一个异步操作，把嵌套的 CompletableFuture 拉平成 CompletableFuture。
- 要串起两个异步 HTTP 请求（比如先查用户 ID，再用 ID 查订单），必须用
thenCompose() - 只是对上一步结果做简单加工（比如把字符串转大写），用
thenApply()更直白 - 用错会导致
CompletableFuture这种类型，编译可能过，但后续> join()会等错对象，甚至抛ClassCastException
userFuture.thenCompose(userId -> orderService.findByUserId(userId)) // ✅ 正确 userFuture.thenApply(userId -> orderService.findByUserId(userId)) // ❌ 返回 CompletableFuture<completablefuture>></completablefuture>
异常没被捕获？别只盯着 whenComplete()
whenComplete() 和 handle() 都能处理完成或异常，但行为完全不同：前者不改变原始 future 的结果，后者可以返回新值并“吞掉”异常；更重要的是，如果在 whenComplete() 里抛出新异常，它不会传播给下游，而是静默丢弃——这会让链路中断得毫无征兆。
- 想记录日志 + 继续传递原结果或异常，用
whenComplete() - 想统一兜底（比如异常时返回默认值），必须用
handle() - 想重试或转换异常类型，得用
exceptionally()，它只在异常时触发，且返回值直接成为新 future 的结果
future.handle((result, ex) -> {
if (ex != null) return Collections.emptyList(); // ✅ 可控兜底
return result;
});
线程池不指定，默认 ForkJoinPool 会吃掉你的阻塞 IO
CompletableFuture 默认用 ForkJoinPool.commonPool()，它按 CPU 核心数分配线程，且假设所有任务都是 CPU 密集型。一旦你在 thenApply() 里调用数据库或 HTTP 客户端（本质是阻塞 IO），线程就会卡住，commonPool 快速耗尽，后续任务无限排队，整个应用变慢甚至假死。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 所有涉及 IO 的回调（
thenApply、thenAccept、thenCompose等），必须显式传入自定义线程池 - 用
Executors.newCachedThreadPool()或固定大小的newFixedThreadPool(N)，N 建议设为 IO 并发预期值（如 50–200） - 千万别用
supplyAsync(() -> {...})不带参数的重载——它默认走 commonPool
CompletableFuture.supplyAsync(() -> db.query("SELECT * FROM user"), ioPool)
.thenApplyAsync(users -> users.size(), ioPool); // ✅ 每个 IO 步都绑定 ioPool
join() 和 get() 在链式里混用会破坏异步性
写到一半忍不住调 join() 或 get() 等结果？这是最隐蔽的“伪异步”陷阱。CompletableFuture 链的本质是注册回调，一旦你主动阻塞，就等于把异步流水线强行切成两段同步执行，不仅失去并发收益，还可能引发线程饥饿和超时连锁反应。
- 链内绝对不要出现
join()、get()、isDone()这类同步方法 - 只有在真正需要最终结果（比如 Controller 返回前、单元测试断言）才调一次
join() - 如果某步逻辑依赖多个 future 结果，用
CompletableFuture.allOf()或CompletableFuture.anyOf()组合，而不是分别join()
复杂点在于：错误堆栈里看不到你 join() 的位置，只看到 TimeoutException 或线程池满——得顺着 call stack 往上翻，看哪层偷偷加了阻塞调用。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
