StructuredTaskScope 是 Java 21 实现结构化并发的核心机制，通过作用域自动强制子任务生命周期与父作用域绑定，解决 ExecutorService 边界模糊、错误传播手动、资源清理不可靠等问题。
结构化并发不是新概念的包装，而是把“谁启动了谁、谁必须等谁、谁出错要通知谁”这些本该明确的事，真正写进语言运行时的行为契约里。Java 21 的 StructuredTaskScope 就是这个契约的执行者——它不靠文档约定，而靠作用域自动强制：子任务不死，父作用域就出不去。
为什么不用 ExecutorService 而要用 StructuredTaskScope
你用 ExecutorService 提交十个任务，然后 shutdown() + awaitTermination()，看似也等完了。但问题在边界模糊：
- 如果某个任务卡住（比如网络 hang 住），
awaitTermination()可能永远不返回，或者你设个超时，但没取消掉还在跑的任务 → 孤儿线程诞生 - 某个任务抛异常，你得自己捕获、自己聚合、自己决定是否中断其余任务 → 错误传播路径是你手动拼的
- 作用域不封闭：任务可能在 try 块外继续执行，和你的业务逻辑“脱钩”
StructuredTaskScope 把这三件事打包成一个动作：进入 try-with-resources 块 → fork 出任务 → join() → 自动清理。失败时直接抛出 ExecutionException，所有未完成任务被级联取消。
StructuredTaskScope 的两种常用子类怎么选
别直接 new StructuredTaskScope，它是个抽象类。实际用这两个之一：
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
-
StructuredTaskScope.ShutdownOnFailure：只要任一子任务失败（抛异常或返回 null），立刻取消其余所有任务，并在join()后统一抛出第一个异常。适合“全有或全无”的场景，比如并行查用户、配置、权限，缺一不可 -
StructuredTaskScope.ShutdownOnSuccess：只要任一子任务成功返回结果，立刻取消其余任务。适合“取最快响应”的场景，比如同时调三个降级缓存源，拿到第一个就停
注意：resultNow() 必须在 join() 之后调，否则可能抛 IllegalStateException；而且它不阻塞，只读当前状态 —— 如果任务还没完成，就返回 null 或抛异常，不是你想要的“等待结果”。
常见错误：在 fork() 里写阻塞代码却忘了虚拟线程
结构化并发本身不解决阻塞问题。如果你在 fork(() -> { Thread.sleep(5000); return "done"; }) 里写平台线程阻塞操作，那这个子任务会占住一个 OS 线程 5 秒，严重拖垮吞吐量。
- 正确做法：搭配虚拟线程使用，比如用
Thread.ofVirtual().start()包一层，或确保 JVM 启动参数含--enable-preview（Java 21+ 已默认启用） - 更稳妥做法：把阻塞 I/O 替换为非阻塞 API（如
HttpClient的异步请求），或用CompletableFuture.supplyAsync(..., executor)配合虚拟线程池 - 切记：
StructuredTaskScope管生命周期，不管调度效率；它和虚拟线程是搭档，不是替代关系
最易被忽略的一点：作用域的“结构化”，本质是代码块的静态嵌套，不是运行时动态关系。你在 lambda 里再 fork 一个 StructuredTaskScope，它就是子作用域，父作用域不会自动感知它的失败 —— 父子关系只存在于显式嵌套的 try 块中。想跨层传递取消信号，得靠 ScopedValue 或显式传入 StructuredTaskScope 实例，不能指望自动穿透。
