Java StructuredTaskScope 怎么设置整体截止时间

如果两个并发子任务必须共享一个总耗时预算，Java 25 的 StructuredTaskScope 应在创建 scope 时配置 withTimeout(Duration)，而不是给每次 fork 各写一个计时器。这个 timeout 从 scope 打开时开始；超时会取消 scope、打断尚未完成的子任务，并让 join() 抛出 StructuredTaskScope.TimeoutException。

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

Java 25 用 withTimeout 配置整个 StructuredTaskScope

下面的示例把两个查询视为一个整体：只要总预算用完，就不再等待它们继续产出结果。Java 25 中 StructuredTaskScope 是预览 API，编译和运行时需要打开 preview。

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

static String loadDashboard() throws InterruptedException {
    try (var scope = StructuredTaskScope.open(
            StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow(),
            config -> config.withTimeout(Duration.ofSeconds(2)))) {
        // 两个子任务共享同一个 scope 级别的两秒预算。
        var profile = scope.fork(() -> queryProfile());
        var orders = scope.fork(() -> queryRecentOrders());

        // 超时、失败或全部完成，结果都从 join 的语义中体现。
        scope.join();
        return profile.get() + " / " + orders.get();
    } catch (StructuredTaskScope.TimeoutException e) {
        // 统一超时只在这里转成业务层的降级结果。
        return "dashboard-timeout";
    }
}

关键不是把 Duration.ofSeconds(2) 传给某个子任务，而是把它交给 scope 的配置函数。计时起点是 open 创建作用域的时刻，因此准备阶段、fork 阶段和 join 等待阶段都要从同一预算中扣除。

超时后的取消、中断与 close 等待

超时不是强行杀死线程。scope 进入取消状态后，会阻止新的子任务启动，并中断尚未完成的子任务；能否很快收尾，取决于子任务使用的阻塞调用是否支持中断。API 的 close() 还会等待这些线程结束，所以不要把捕获 TimeoutException 理解成所有后台工作已经立刻消失。

static String queryProfile() throws InterruptedException {
    try {
        // 示例用可中断等待模拟远端调用，真实客户端也要配置自己的超时。
        Thread.sleep(1_500);
        return "profile-ok";
    } finally {
        // 释放连接、游标或临时资源；收到中断后不能静默吞掉信号。
        if (Thread.currentThread().isInterrupted()) {
            throw new InterruptedException("profile task cancelled");
        }
    }
}

生产代码里要特别检查三类风险：第一，底层 HTTP、数据库或文件调用是否会响应线程中断；第二，catch (InterruptedException) 是否恢复中断状态或继续向上抛出；第三，外部依赖是否还需要自己的连接级 timeout。scope 级 deadline 负责并发协作的总预算，不能替代每个网络调用的连接、读取和重试边界。

参数与版本边界要先分清

如果项目仍停留在较早的 Structured Concurrency 预览版本，可能看到的是 joinUntil(Instant deadline)，那是等待时传入绝对截止时刻的写法。不要把旧版示例直接复制到 Java 25：先确认目标 JDK 的 API，再选择 withTimeout(Duration) 或对应版本的等待方法。无论哪种写法，子任务都必须可取消，外层业务也要保留自己的返回与降级策略。

相关问题

withTimeout 会给每个 fork 单独分配两秒吗？

不会。它给整个 scope 配置一份共享预算，所有子任务共同消耗从 scope 打开时开始的这段时间。

捕获 TimeoutException 后还要关闭 scope 吗？

要。推荐使用 try-with-resources，让 close 自动执行；同时确保子任务不会吞掉中断，否则 close 可能等待更久。

scope 超时能替代 HTTP 客户端超时吗？

不能完全替代。scope 负责并发任务的总边界，HTTP 客户端仍应配置连接、读取和重试超时，避免底层调用无法及时响应中断。