StructuredTaskScope 如何表达并发任务的共同生命周期

如果一项请求要同时读取用户资料和订单摘要，两个子任务都属于这次请求：请求结束前它们应该收敛，任一失败时也要有明确的取消边界。Java 25 的预览 API StructuredTaskScope正是用一个词法作用域表达这层关系：在作用域内 fork，用 join等待，再由 try-with-resources 触发 close。它解决的是并发任务的共同生命周期，不是简单换一种线程池写法。

官方资料：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/StructuredTaskScope.html

StructuredTaskScope 管理的不是线程数量，而是任务边界

传统 ExecutorService 加 Future 的代码，容易把提交、等待、取消分散到不同方法，调用方很难看出还有哪些线程没有结束。StructuredTaskScope 把 owner、subtask 和 scope 组织成层级：owner 打开 scope，子任务在其中 fork，owner join 后才能离开资源块，close 会阻止继续创建并处理中止中的子任务。

从 Future 收集改成 scope、fork、join、close

下面的例子把两个独立读取并发执行，只有两个结果都成功后才组装视图。代码故意把 join 放在结果读取之前，因为子任务尚未完成时调用 Subtask.get() 并不能代替等待。

import java.util.concurrent.StructuredTaskScope;

record UserView(String profile, String orders) {}

static UserView loadUserView(long userId) throws Exception {
    // scope 绑定这次请求；退出资源块前，子任务必须完成或被取消
    try (var scope = StructuredTaskScope.open()) {
        var profile = scope.fork(() -> loadProfile(userId));
        var orders = scope.fork(() -> loadOrders(userId));

        // join 统一等待两个子任务，并把失败交给 scope 的默认策略
        scope.join();
        // join 成功后读取结果，避免在未完成状态下取值
        return new UserView(profile.get(), orders.get());
    } catch (InterruptedException e) {
        // 保留中断信号，让上层决定是否重试或返回取消
        Thread.currentThread().interrupt();
        throw e;
    }
}

static String loadProfile(long userId) { return "profile-" + userId; }
static String loadOrders(long userId) { return "orders-" + userId; }

默认 open() 的策略是所有子任务成功才正常返回；任一子任务失败，join 会抛出 FailedException。如果子任务结果类型一致，可以用 Joiner.allSuccessfulOrThrow() 收集；如果只要第一个成功结果，可用 anySuccessfulResultOrThrow()；只关心全部完成而不让失败自动取消，则选 awaitAll()。

失败、超时和取消要一起设计

超时要配置在 scope 上，而不是只给某一个 Future 加等待时间。Java 25 的配置可以设置名称、线程工厂和超时；超时从 scope 打开时开始计时，join 会以 TimeoutException 表示结果。

import java.time.Duration;
import java.util.concurrent.StructuredTaskScope;

static void refreshCache() throws InterruptedException {
    // 配置总预算，避免两个子任务各自等待导致请求总时长失控
    try (var scope = StructuredTaskScope.open(
            StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow(),
            config -> config.withTimeout(Duration.ofSeconds(2)))) {
        scope.fork(() -> { refreshProfileCache(); return null; });
        scope.fork(() -> { refreshOrderCache(); return null; });
        // 任一子任务失败或总预算耗尽，join 给出统一结果
        scope.join();
    } catch (StructuredTaskScope.TimeoutException e) {
        // 记录超时并让调用方选择降级，不要静默吞掉取消
        throw e;
    } catch (StructuredTaskScope.FailedException e) {
        // cause 才是首个失败子任务的业务异常
        throw new IllegalStateException("cache refresh failed", e.getCause());
    }
}

static void refreshProfileCache() {}
static void refreshOrderCache() {}

这里的异常边界有三个判断：第一，子任务要能响应中断，阻塞 I/O 也要选择可取消的实现；第二，捕获 InterruptedException 后恢复中断状态；第三，不能把长生命周期消费循环硬塞进一次请求 scope，因为它的完成条件与请求不一致。对需要长期运行的任务，仍应单独设计生命周期和关闭协议。

迁移前的回归清单

从 Future 迁移时先确认四件事：业务是否真的要求子任务共同完成；失败时是全部取消还是允许部分结果；超时是单任务预算还是整个 scope 预算；监控是否需要给 scope 设置名称。还要把编译与运行参数写进构建配置：

# Java 25 预览 API 必须同时在编译和运行阶段启用
javac --enable-preview --release 25 UserViewDemo.java
java --enable-preview UserViewDemo

最后检查生产 JDK 与 CI 的版本一致性。StructuredTaskScope 在 Java 25 文档中仍标注为预览 API，未来版本可能调整或移除；因此它适合已经接受预览特性、并能集中管理升级风险的模块，不适合在没有兼容性策略的公共库里悄悄暴露 API。

相关问题

StructuredTaskScope 会自动创建虚拟线程吗？

默认配置使用为每个子任务创建的虚拟线程，也可以通过配置提供线程工厂。是否适合使用仍取决于阻塞点和任务的生命周期。

为什么必须调用 join？

join 是 owner 对 scope 的收敛动作。只 fork 不 join 就离开资源块，会让 close 进入取消与收尾路径，并可能触发使用约束异常。

StructuredTaskScope 能替代所有线程池吗？

不能。它适合有明确父子关系、需要共同完成或共同取消的短生命周期任务；长期后台任务、无界消费和独立调度仍应使用匹配其生命周期的组件。