Java StructuredTaskScope 怎么在子任务失败时取消同组任务

当一个页面同时读取用户资料和订单列表时，两个子任务通常是“要么一起成功，要么整体失败”。当前 JDK 26 的做法是把它们放进同一个 StructuredTaskScope，使用 Joiner.awaitAllSuccessfulOrThrow()：任一子任务失败，scope 取消并中断尚未完成的兄弟任务，owner 从 join() 得到失败原因。

官方地址：https://docs.oracle.com/en/java/javase/26/core/structured-concurrency.html

失败如何触发同组取消

把“失败策略”放在 scope 的 Joiner 上，而不是让每个子任务互相持有线程引用。下面的代码展示两个返回类型不同的任务：资料加载失败后，订单加载会收到中断；只有 join() 正常返回，才能调用 Subtask.get()。

import java.util.List;
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;
import java.util.concurrent.StructuredTaskScope.Joiner;

static UserSummary loadPage(long userId) throws InterruptedException {
    // awaitAllSuccessfulOrThrow 表示任一失败都不再需要其他结果
    try (var scope = StructuredTaskScope.open(Joiner.awaitAllSuccessfulOrThrow())) {
        Subtask user = scope.fork(() -> loadUser(userId));
        Subtask> orders = scope.fork(() -> loadOrders(userId));

        // owner 统一等待；失败时 Joiner 会取消未完成的兄弟任务
        scope.join();
        return new UserSummary(user.get(), orders.get());
    } catch (StructuredTaskScope.FailedException e) {
        // 保留首个失败原因，交给上层决定返回错误还是重试
        throw new IllegalStateException("页面聚合失败", e.getCause());
    }
}

这里的关键不是“主动找到另一条线程再调用 interrupt”，而是 Joiner 让失败条件成为 scope 的统一策略。JDK 26 文档中的无参 open() 也采用“任一子任务失败就抛出 FailedException”的默认策略；显式写 Joiner 更适合把意图留在代码里。

join、get 和 close 各自负责什么

容易混淆的是三个边界：fork 只创建并启动子任务，join 由 scope owner 等待并得到 Joiner 的结果，get 只读取已经成功完成的子任务结果。失败路径不要在 join 之前读取 get，因为兄弟任务可能仍处于不可用状态。

try-with-resources 很重要：即使 owner 在 join 后抛出业务异常，离开代码块仍会关闭 scope。关闭动作会打断尚未结束的任务，并等待它们真正终止，所以它是资源生命周期的最后一道边界，而不是“发出中断后立即返回”。

被中断的子任务为什么还要配合退出

取消只提供中断信号，不能强行杀掉 Java 线程。网络客户端、锁或自定义循环如果吞掉 InterruptedException，scope 可能在 close() 处等待很久。子任务应在捕获中断后恢复中断标记、退出当前任务，并把文件、连接或临时状态放进 finally。

static List loadOrders(long userId) throws InterruptedException {
    try (var client = openOrderClient()) {
        // 可中断等待结束后，把取消信号继续交给 scope
        return client.fetch(userId);
    } catch (InterruptedException e) {
        // 不要吞掉中断，否则 close 可能一直等不到线程结束
        Thread.currentThread().interrupt();
        throw e;
    } finally {
        // 无论成功、失败或取消，都清理本地临时资源
        clearRequestLocalCache();
    }
}

哪些场景不应使用失败即取消

如果业务允许部分结果，例如多个镜像站点竞速取一个成功值，应选择 Joiner.anySuccessfulResultOrThrow()；如果必须收集所有成功和失败，再考虑 Joiner.awaitAll() 或自定义 Joiner。不要因为“并发”三个字就默认全组失败：是否取消取决于剩余结果还有没有业务价值。

还要留意版本边界：StructuredTaskScope 在 JDK 26 仍是预览 API，编译运行需要启用预览特性，例如 javac --enable-preview --release 26 与 java --enable-preview。JDK 21–24 的示例常见 new StructuredTaskScope.ShutdownOnFailure()，那是旧预览形态；迁移到当前 API 时应重新核对 Joiner、异常类型和结果读取方式。

# 编译当前 JDK 26 预览 API；源文件名按实际项目替换
javac --enable-preview --release 26 PageLoader.java
# 运行时同样开启预览特性
java --enable-preview PageLoader

常见问题

子任务失败后，兄弟任务一定立刻停止吗？

不一定。scope 会发出中断并阻止新的子任务启动，但兄弟任务必须调用可中断 API 或主动检查中断；不配合的代码会拖慢 close。

为什么不能在 join 之前调用 Subtask.get？

因为此时结果可能尚未完成，甚至已因 scope 取消而不可用。先让 owner 完成 join，再读取成功状态的结果。

旧版 ShutdownOnFailure 代码能直接复制到 JDK 26 吗？

不能把它当作当前写法。JDK 26 使用 StructuredTaskScope.open 与 Joiner，预览 API 仍可能变化，应以对应 JDK 的 API 文档为准。