Java 26 StructuredTaskScope 如何设置超时：Joiner 与取消边界

两个远程读取同时发起时，最怕的不是其中一个慢，而是慢任务把整个请求的结束时间拖成不可控。Java 26 的 StructuredTaskScope 可以把子任务放进一个作用域，并在打开作用域时设置超时；但它仍是预览 API，join() 的等待、超时取消和 close() 的收尾必须一起理解。

先确认 Java 26 与预览 API 的运行边界

StructuredTaskScope 是 Java SE 26 的预览 API，不能把示例当成普通 Java 代码直接编译。先确认本机 JDK 与编译器来自同一大版本：

java -version
javac -version
javac --enable-preview --release 26 Demo.java
java --enable-preview Demo

如果编译器不是 JDK 26，--release 26 会直接失败；如果启动时漏掉 --enable-preview，编译通过的预览类也不能按这个示例运行。这个检查应放在 CI 的编译命令里，而不是只靠开发机记忆。

用 open 配置一个有时间边界的作用域

假设页面需要同时读取库存和运费。这里使用 StructuredTaskScope、fork、join 和 TimeoutException 四个真实节点：作用域打开后启动两个子任务，等待结果时由超时配置决定是否取消。

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

static String loadPageData() throws Exception {
    var timeout = Duration.ofSeconds(2);
    try (var scope = StructuredTaskScope.open(
            StructuredTaskScope.Joiner.allSuccessfulOrThrow(),
            config -> config.withTimeout(timeout))) {

        var stock = scope.fork(() -> loadStock());
        var freight = scope.fork(() -> loadFreight());

        var results = scope.join();
        return results.stream()
                .map(StructuredTaskScope.Subtask::get)
                .toList()
                .toString();
    } catch (StructuredTaskScope.TimeoutException e) {
        throw new IllegalStateException("page data timed out", e);
    } catch (StructuredTaskScope.FailedException e) {
        throw new IllegalStateException("page data failed", e.getCause());
    }
}

Joiner.allSuccessfulOrThrow() 表示所有子任务成功后才形成结果；一旦某个子任务失败，作用域会按 joiner 的规则结束。withTimeout(timeout) 的计时从 open 创建作用域时开始，所以准备工作不能无限期塞在作用域内部。

超时发生时，取消和线程退出不是同一个瞬间

当两秒窗口耗尽时，join() 会因超时结束等待，作用域进入取消流程，未完成的子任务会收到中断信号。这里的中断只是协作式通知，不会强行杀掉正在执行的代码；loadStock 和 loadFreight 使用的底层客户端必须能响应中断或自己的超时。

static String loadFreight() throws InterruptedException {
    try {
        Thread.sleep(5_000);
        return "freight-ok";
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        return "freight-cancelled";
    }
}

不要在 catch (InterruptedException) 里什么都不做。若任务吞掉中断后继续等待，try-with-resources 的 close() 仍需等待它结束，调用线程就可能在异常处理之后继续卡住。可观察的成功状态应是：超时异常被记录，未完成任务停止，作用域关闭后方法返回。

Joiner 结果与异常处理要分开验收

join() 不只是一个等待点，它还会返回配置的 Joiner 产物。使用 allSuccessfulOrThrow 时，调用方应把三种结果分开检查：

不要用一个“返回空字符串”的默认值掩盖三种状态。页面可以选择降级展示，但日志和指标仍应区分“依赖失败”和“超时取消”，否则后续无法判断是服务慢还是服务已经报错。

上线前做一次关闭路径复查

把示例放进真实服务前，至少做四项检查：编译和启动都带 --enable-preview；超时从作用域打开时开始计时；所有子任务都在 join 前 fork；取消后每个阻塞调用都有退出路径。Java 26 文档还要求作用域由拥有它的线程调用 fork、join 和 close，不要把 scope 对象交给另一个线程操作。

这套 API 仍在预览阶段，版本升级时要重新核对方法签名和异常类型。若业务不能接受预览特性带来的兼容风险，应继续使用项目已经验证过的并发抽象，把本文的超时、取消、结果分层思路保留下来即可。

常见问题：StructuredTaskScope 超时边界

超时配置从什么时候开始计算？

从打开 StructuredTaskScope 时开始，而不是从调用 join() 时才开始。

超时后 close 会立即返回吗？

不会。作用域会取消未完成任务，并等待由它启动的线程结束；任务是否及时响应中断会影响收尾时间。

可以在 join 之后继续 fork 吗？

不可以。Java 26 API 的使用约束要求先完成 fork，再调用 join；join 之后不能追加子任务。

StructuredTaskScope 是正式 API 吗？

Java 26 文档将它标为预览 API。编译、运行和升级验证都要显式处理预览特性，不能当作跨版本稳定契约。

实际接入时，先用一个可控的两个子任务测试超时和中断，再把依赖客户端的关闭行为纳入回归测试。真正需要验收的不是异常是否抛出，而是超时之后没有遗留仍在运行的子任务。