Java StructuredTaskScope 失败传播和取消顺序如何读

读 Java StructuredTaskScope 的失败传播，先记住一句话：失败的子任务让 joiner 取消 scope，未完成的兄弟任务收到中断请求，join() 再把失败包装成 StructuredTaskScope.FailedException；但中断请求不等于线程已经退出，close() 仍会等待这些子任务结束。

判断日志时按“失败 cause、取消状态、关闭等待”三层看，不要把某个子任务先打印日志理解成整个 scope 已经完成。

先看懂 StructuredTaskScope 的失败传播链

下面的示例使用 Java 25 的 Joiner.awaitAllSuccessfulOrThrow()。两个子任务都成功时，join() 正常返回；任一子任务失败时，joiner 取消 scope，并让 join() 抛出 FailedException。示例里的 load() 只代表业务调用，重点是结果和异常的读取位置。

import java.util.concurrent.StructuredTaskScope;

static String aggregate() throws InterruptedException {
    try (var scope = StructuredTaskScope.open(
            StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow())) {
        // 两个任务属于同一个作用域，joiner 统一决定成功或失败出口
        var profile = scope.fork(() -> load("profile"));
        var orders = scope.fork(() -> load("orders"));

        scope.join();
        // 只有 join 成功后才读取成功子任务的结果
        return profile.get() + " / " + orders.get();
    } catch (StructuredTaskScope.FailedException ex) {
        // 外层异常说明 joiner 产生了失败结果，真正原因在 cause
        throw new IllegalStateException("并发聚合失败", ex.getCause());
    }
}

这里有两个容易混淆的点。第一，FailedException 是 join() 的结果包装，不是业务子任务抛出的原始异常；排查时要继续看 ex.getCause()。第二，默认的失败策略关注“任一任务失败”，并不保证你能从两个并发日志的打印时间推导出稳定顺序。

取消请求和 close 等待要分开看

当 joiner 发现失败，scope 会进入取消状态，并中断仍在执行的子任务。被中断的任务是否马上结束，取决于它是否正确响应 InterruptedException 或检查中断标记。close() 的职责更严格：它会取消 scope，然后等待所有子任务结束，所以 try-with-resources 代码块可能在异常已经出现后仍停留一段时间。

因此，子任务里不要吞掉中断后继续做长时间工作。对可中断阻塞调用，捕获异常后先做必要清理，再恢复中断状态或把异常交给上层；对不响应中断的外部调用，要单独设置它自己的超时，否则 scope 关闭也可能被拖住。

用三个信号判断失败到底走到了哪一步

记录并发任务时，建议把异常原因、取消状态和关闭完成分别作为日志字段，而不是只打一行“任务失败”。例如可以在调用方捕获包装异常，在清理逻辑里读取取消状态：

try (var scope = StructuredTaskScope.open(
        StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow())) {
    // 子任务应在阻塞调用处处理取消，避免 close 长时间等待
    scope.fork(() -> fetchWithInterruptCheck());
    scope.fork(() -> fetchWithInterruptCheck());
    try {
        scope.join();
    } catch (StructuredTaskScope.FailedException ex) {
        // 记录 cause 和取消状态，二者分别回答“谁失败”和“是否在收尾”
        logFailure(ex.getCause(), scope.isCancelled());
        throw ex;
    }
} // 走到这里表示 close 已经完成等待

这段代码里的日志仍然只是调用方观察点：scope.isCancelled() 可能在所有子任务完成前就返回 true。若需要确认清理动作完成，把清理放在子任务自己的 finally 中，并让调用方只把离开 try-with-resources 作为 scope 关闭完成的边界。

常见问题

FailedException 为什么不直接等于子任务异常？

它是 join() 对 joiner 异常结果的统一包装，原始失败通常在 getCause() 中；多任务并发失败时，不要假设业务启动顺序就是 cause 选择顺序。

scope 取消后兄弟任务一定立刻停止吗？

不一定。取消会请求中断，任务必须响应中断；不响应的阻塞调用仍可能让 close() 等待。

Java 25 能直接在生产环境使用这个 API 吗？

StructuredTaskScope 在 Java SE 25 文档中仍标为预览 API。使用前应明确启用 preview，并把 JDK 版本、编译参数和回滚方案纳入项目约束。