Java StructuredTaskScope 怎么收集部分成功结果：失败策略、关闭时机与回收验收

做一个聚合接口时，用户资料、权限摘要和推荐标签往往可以并行查询。真正麻烦的地方不是把三个任务同时发出去，而是其中一个失败后，已经完成的结果要不要保留、剩余任务何时停止，以及离开作用域后有没有线程或资源没有收干净。Java 的 StructuredTaskScope 可以把这段生命周期放进一个明确的作用域里，本文用一个可运行的小实验把这些边界串起来。

先把部分成功定义清楚

“部分成功”不是忽略异常。这个示例把资料、权限、标签看成三个互不依赖的读取动作：资料和标签成功、权限失败时，页面可以返回已完成的两块，同时把权限块标成不可用；如果资料本身失败，则整个聚合结果没有继续展示的价值。

因此要先决定失败策略。ShutdownOnFailure 适合“任何一个关键子任务失败，就尽快取消同一作用域内的其他任务”的场景。它不会替你定义业务降级，哪些结果可以保留仍然要由调用方明确判断。

准备一个能观察状态的最小实验

下面的代码使用 Java 25 的结构化并发预览 API。不同 JDK 的预览接口可能继续调整，运行前请让编译器和运行时版本一致，并开启对应的 preview 选项。

import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.atomic.AtomicInteger;

public class PartialResultsDemo {
    static final AtomicInteger cancelled = new AtomicInteger();

    static String load(String name, long millis, boolean fail) throws Exception {
        try {
            Thread.sleep(millis);
            if (fail) throw new IllegalStateException(name + " lookup failed");
            return name + "-ok";
        } catch (InterruptedException e) {
            cancelled.incrementAndGet();
            throw e;
        }
    }

    public static void main(String[] args) throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            var profile = scope.fork(() -> load("profile", 80, false));
            var permission = scope.fork(() -> load("permission", 30, true));
            var tags = scope.fork(() -> load("tags", 300, false));

            scope.join();
            var failure = scope.exception();
            System.out.println("failure=" + failure.map(Throwable::getMessage).orElse("none"));
            System.out.println("profile=" + profile.state());
            System.out.println("permission=" + permission.state());
            System.out.println("tags=" + tags.state());
            System.out.println("cancelled=" + cancelled.get());
        }
    }
}

这里故意让权限读取先失败，标签读取需要更久。catch 只负责记录被中断的子任务并继续传播中断；不要把中断吞掉，否则关闭动作看似完成，实际任务可能还在后台运行。

按顺序完成 fork、join 和失败判断

fork() 只是提交子任务，不能代表任务已经完成。必须先调用 join()，再读取失败状态或子任务状态。ShutdownOnFailure 发现异常后会请求其他子任务停止，所以较慢的标签读取通常会进入失败或取消相关状态，而不是保证拿到一个完整字符串。

如果业务允许“每块独立成功”，就不要把所有动作都放入一个遇错即停的策略里。可以改用基础作用域，分别检查每个子任务的状态，并把异常转换成聚合响应中的可见错误。这个取舍要写进接口契约，不能靠调用方猜。

为什么 close 不是可有可无的一行

结构化并发的价值在于子任务生命周期不能逃出父任务。使用 try-with-resources 后，正常路径和异常路径都会进入关闭流程；如果手工创建作用域却忘记关闭，代码 review 很难判断子任务是否已经收敛。

关闭前应完成三项检查：第一，join() 已经返回；第二，失败信息已经转换成业务可读的结果；第三，慢任务在被取消后确实响应中断。可以把取消计数、任务状态和关键耗时写入测试日志，但不要用一个“打印完成”就宣称回收成功。

用两组实验验收边界

第一组让关键任务失败，观察其他任务是否收到中断，并确认 failure 不为空。第二组把所有任务都改成成功，确认三个结果都能在作用域内读取，关闭后没有额外线程继续输出日志。

编译和运行命令要与本机 JDK 对齐，例如：

javac --enable-preview --release 25 PartialResultsDemo.java
java --enable-preview PartialResultsDemo

不要只看进程退出码。更可靠的验收记录至少包括：失败任务的异常消息、慢任务最终状态、取消计数是否增加，以及 try-with-resources 之后没有第二次业务输出。若你的 JDK 仍未提供这组预览 API，应先升级到匹配版本或改写为现有并发工具，不要只复制命令强行编译。

几个容易写错的边界

把 exception 当成所有结果都不可用

失败策略报告的是作用域内出现了异常，不等于已经完成的非关键结果全部失效。是否保留资料和标签，应由业务字段决定；读取每个子任务前仍要检查它的状态。

在 join 之前读取结果

子任务的结果只有在等待完成后才有稳定语义。提前读取会把“尚未完成”误判成空值或失败，尤其在本地测试速度很快时更容易被掩盖。

忽略中断异常

取消是协作式的。任务内部如果捕获中断后继续执行耗时工作，父作用域只能等待它真正退出。外部 IO 也要设置自己的超时，并在清理分支关闭连接或响应体。

落地前的检查清单

• 每个子任务是否都有清晰的关键性定义和失败语义。
• 是否在读取结果前完成了 join()，并记录了异常来源。
• 慢任务是否能响应中断，阻塞 IO 是否另有超时。
• 作用域是否由 try-with-resources 管理，关闭后是否有回收证据。
• 预览 API 的 JDK、编译参数和运行参数是否完全匹配。

相关问题

所有子任务都必须使用虚拟线程吗？

不应把线程实现和失败策略混为一谈。结构化作用域解决的是任务层级与生命周期，具体线程选择还要结合阻塞特征、调用链和部署版本验证。

部分成功响应要不要返回 HTTP 成功？

这取决于接口契约。可以返回成功状态并在每个结果块携带状态，也可以把关键块失败映射为整体失败；重点是让客户端能区分“没有数据”和“读取失败”。

总结

StructuredTaskScope 的使用重点不在于少写几行线程代码，而在于把 fork、等待、失败传播、取消和关闭放进同一条可验收的生命周期。先选对失败策略，再用状态、异常和中断计数验证结果，部分成功才不会变成悄悄丢错的接口响应。