Java StructuredTaskScope组织子任务取消与结果汇总的实现方法

我第一次把一个“同时查用户资料和额度”的 Java 方法改成结构化并发时，最在意的不是多开两条线程，而是失败以后谁负责收尾。StructuredTaskScope 的价值正在这里：子任务被放进一个明确的作用域，父线程统一 join，作用域关闭前不会把仍在运行的子线程遗留给调用方。

需要“同一个父任务创建子任务、任一失败就取消未完成任务、全部成功后再汇总”的场景，可以优先考虑 StructuredTaskScope；但它在当前 Java SE 26 仍是 preview API，生产采用前要锁定 JDK 与预览开关。

StructuredTaskScope先把生命周期收进一个作用域

当前 API 用 StructuredTaskScope.open() 打开作用域，默认通过虚拟线程运行被 fork 的子任务。打开作用域的线程就是 owner，只有它能继续 fork、join 和 close。这个限制看似严格，却让“谁创建、谁等待、谁收尾”变得清楚。

join之后再读取 Subtask 并完成结果汇总

下面的例子把两个不同来源的字符串收敛成一个记录。重点是先保存 fork 返回的 Subtask，再调用 join，最后才读取 get。get 不是“立即取值”的 Future 式偷跑，它要求子任务已经完成且 owner 已经 join。

import java.util.concurrent.StructuredTaskScope;

record UserParts(String profile, String quota) {}

static UserParts loadUserParts() throws Exception {
    // 一个作用域绑定一次调用；try-with-resources 负责最终 close。
    try (var scope = StructuredTaskScope.open()) {
        var profile = scope.fork(() -> query("profile"));
        var quota = scope.fork(() -> query("quota"));

        // 先等所有子任务完成或作用域因失败而取消。
        scope.join();

        // join 之后才能安全读取成功子任务的结果。
        return new UserParts(profile.get(), quota.get());
    } catch (StructuredTaskScope.FailedException ex) {
        // 将首个失败原因带回业务层，避免吞掉真正的异常。
        throw new IllegalStateException("用户资料汇总失败", ex.getCause());
    }
}

static String query(String part) throws InterruptedException {
    try {
        // 用延迟模拟外部调用；真实客户端也必须有可中断的等待点。
        Thread.sleep(80);
        return part + "-result";
    } catch (InterruptedException ex) {
        // 取消通过中断到达，恢复标记后把异常继续向上交给作用域。
        Thread.currentThread().interrupt();
        throw ex;
    }
}

编译这段示例时应使用与目标 JDK 一致的预览参数，例如 javac --enable-preview --release 26 Example.java，运行时再加 java --enable-preview Example。这里的命令只说明编译方式，不代表本文在本机执行了示例。

失败取消不是强杀，任务必须配合中断

默认作用域的 joiner 关注“全部成功或有任务失败”。如果一个子任务先失败，未完成的同级任务会被取消，底层通常表现为对执行线程发出 interrupt。它不是强制杀线程：正在执行不可中断阻塞、吞掉 InterruptedException 或卡在外部客户端里的任务，仍可能拖慢作用域退出。

因此取消路径要和业务调用一起设计。阻塞 I/O 选支持超时和中断的客户端；捕获中断时恢复线程标记并继续抛出；不要在 finally 里重新启动已经被取消的工作。close 还会等待未完成任务结束，所以它是资源回收边界，不是绕过清理的快捷键。

三种方案按父子关系和复用方式选择

我实际做选型时只看三个问题：这批任务是否只服务一次调用，失败是否需要同级联动取消，结果是否要在一个父任务里同步收口。答案都偏“是”时，StructuredTaskScope 的表达最直接。

如果业务只需要“谁先成功就返回”，可以改用带合并策略的 Joiner；如果必须保证所有结果齐全，则继续使用默认的全成功语义并逐个 get。不要因为代码更短就把三种方案当成同一种抽象。

常见问题

StructuredTaskScope能否在子线程里调用join？

不能。作用域由打开它的 owner 线程管理，fork、join、close 都应由 owner 调用；子任务只负责执行自己的 Callable。

为什么join之后还要判断任务状态？

因为取消或失败时，某个 Subtask 可能没有成功结果。只有在 join 正常完成且该子任务成功时，才读取 get；失败应沿异常路径处理。

StructuredTaskScope已经是正式 API 吗？

Java SE 26 API 仍将它标为 preview。升级 JDK 后要重新核对方法签名、预览开关和部署策略，不能只替换运行时版本。

这套写法的核心不是把线程藏起来，而是把线程的出生、等待、取消和结束放回同一个调用边界。需要一次性并发聚合时，我会先用它建模；需要跨生命周期的异步编排或长期执行器时，再回到 CompletableFuture 或 ExecutorService。