StructuredTaskScope 是 Java 21 引入的结构化并发原语，专为父子任务生命周期强绑定场景设计，解决子任务孤儿、异常丢失、中断失效等问题；它要求任务在同作用域内启动并统一管理生命周期。
StructuredTaskScope 是什么，它解决什么问题
Java 21 的 StructuredTaskScope 不是线程池替代品，也不是通用并发工具；它是为「有明确父子生命周期边界的协同任务」设计的结构化并发原语。核心价值在于：当一组子任务必须和父任务共存亡（父任务取消/完成 → 子任务强制中断），且需要统一收集结果或异常时，它比 ForkJoinPool + CompletableFuture 手动管理更安全、更可预测。
常见错误现象：InterruptedException 被吞掉、子任务变成“孤儿线程”持续运行、join() 卡死不返回、多个异常被丢弃只剩最后一个。
- 它要求所有子任务在同一个
StructuredTaskScope实例内启动，且必须在scope.close()（或 try-with-resources 结束）前完成或被中断 - 不支持异步回调、不兼容
ExecutorService.submit()风格的自由提交 - 一旦 scope 关闭，再调用
fork()会抛IllegalStateException
怎么正确使用 StructuredTaskScope.Unstructured 和 StructuredTaskScope.ShutdownOnFailure
选错子类是高频翻车点。Java 21 提供两个开箱即用实现，行为差异极大：
-
StructuredTaskScope.Unstructured：最宽松，不自动中断其他子任务，即使某个失败也继续等全部结束。适合“尽最大努力执行，结果各自独立”的场景，比如批量发日志、上报指标 -
StructuredTaskScope.ShutdownOnFailure：任一子任务抛未捕获异常 → 立即中断其余正在运行的子任务，并在join()时抛出第一个异常。适合“全成功才有效”的协作任务，比如并行查库存+扣积分+发消息
使用场景决定选择：
立即学习“Java免费学习笔记（深入）”；
- 需要“只要一个失败就立刻停手”，用
ShutdownOnFailure - 需要“不管谁失败，都等所有人跑完再汇总”，用
Unstructured - 没有现成子类满足？别自己继承 —— 它的构造函数是 package-private，官方不开放自定义策略
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
var handle1 = scope.fork(() -> fetchUser(id));
var handle2 = scope.fork(() -> fetchOrder(id));
scope.join(); // 阻塞直到全部完成，或任一失败
scope.throwIfFailed(); // 抛出第一个异常（如果有的话）
}
为什么不能直接用 join() 而要配合 throwIfFailed()
join() 只负责等待完成，不传播异常。这是最容易忽略的设计细节：子任务抛出的异常被静默捕获并存入内部状态，不 rethrow，也不中断当前线程。
- 如果只调
scope.join()，然后直接取handle.get()，可能触发ExecutionException或NullPointerException（因 handle.result() 为 null） - 正确流程必须是：先
join()，再显式调throwIfFailed()—— 后者才是异常出口 -
throwIfFailed()只抛第一个异常，不会打包成ExecutionException，就是原始异常类型（比如IOException），便于 catch 分支处理
性能影响：无额外开销。throwIfFailed() 是纯状态检查，不涉及线程调度或锁竞争。
常见陷阱：作用域泄漏、异常掩盖、与虚拟线程混用时的误区
-
作用域没关闭：忘记 try-with-resources 或漏写
scope.close() → 子任务线程无法被 GC，可能引发线程泄漏。尤其在 Web 请求短生命周期中，极易堆积
-
异常被覆盖：在
ShutdownOnFailure 下，若多个子任务同时失败，只有第一个异常能被 throwIfFailed() 捕获；其余异常需通过 handle.exception() 手动遍历获取，否则丢失
-
误以为和虚拟线程强绑定：虽然
StructuredTaskScope 默认使用 Thread.ofVirtual().unstarted() 创建子任务线程，但它也能工作在平台线程上（传入自定义 ThreadFactory）。但若手动传入共享的 ThreadPoolExecutor，会破坏结构化语义 —— 因为线程复用导致生命周期不可控
-
和 CompletableFuture 混用危险：不要在
fork() 里返回 CompletableFuture 并调 join() —— 这会导致阻塞式等待，违背结构化并发的协作前提；应确保 fork() 内部是真正同步或可中断的阻塞操作（如 InputStream.read()、Socket.connect()）
scope.close() → 子任务线程无法被 GC，可能引发线程泄漏。尤其在 Web 请求短生命周期中，极易堆积 ShutdownOnFailure 下，若多个子任务同时失败，只有第一个异常能被 throwIfFailed() 捕获；其余异常需通过 handle.exception() 手动遍历获取，否则丢失 StructuredTaskScope 默认使用 Thread.ofVirtual().unstarted() 创建子任务线程，但它也能工作在平台线程上（传入自定义 ThreadFactory）。但若手动传入共享的 ThreadPoolExecutor，会破坏结构化语义 —— 因为线程复用导致生命周期不可控 fork() 里返回 CompletableFuture 并调 join() —— 这会导致阻塞式等待，违背结构化并发的协作前提；应确保 fork() 内部是真正同步或可中断的阻塞操作（如 InputStream.read()、Socket.connect()）事情说清了就结束。
