Java ScopedValue 怎样把请求上下文传给子任务

把请求上下文传给结构化子任务，关键是先用 ScopedValue.where(...).call(...) 建立绑定，再在绑定内部打开 StructuredTaskScope 并派生任务。子任务中的业务方法通过同一个 key 调用 get()，就能读取继承的上下文；任务作用域关闭后，外层绑定才能退出。任意线程池提交都自动继承上下文的假设并不成立。

官方地址：https://docs.oracle.com/en/java/javase/25/

下面固定采用 JDK 25 的 API 写法：ScopedValue 在这个版本已经是正式 API，而 StructuredTaskScope 仍是预览 API，完整示例因此需要预览开关。不要把旧版的结构化并发类名和构造方式混进这一份代码，也不要把示例理解为所有 JDK 版本通用的写法。

来源与校验：请求入口只准备必要的只读数据

这里的上下文只包含 requestId 与 tenantId。入口完成身份和租户判定后，构造一个不可变记录，再把它绑定到当前请求。ScopedValue 负责可见范围，不代替身份校验，也不会替你判断租户字符串是否合法。

不要把整个可变请求对象塞进去。上下文可能同时被多个子任务读取，简单的字符串字段能让共享关系清楚；若记录的字段是可变集合，record 也不会自动把集合深度冻结。确实需要共享可变对象时，必须另外设计同步方式。本文采用只有字符串的记录，把讨论限定在读取与生命周期。

存储模型：静态 key 不等于全局请求变量

ScopedValue.newInstance() 创建的是 key，通常放在私有静态 final 字段中。它可以长期存在，但并没有把某个请求永久保存成全局值。真正的请求值在调用 where 之后，由 call 或 run 所限定的执行范围提供。单独创建 carrier 不会立即使当前线程获得绑定。

可以把它理解为稳定的查询入口加上有边界的当前值，而不是到处传递同一个全局可写槽位。不同请求各自进入自己的绑定范围，业务层只读取当前范围的值。需要更小的局部上下文时，还可以嵌套绑定；内层结束后恢复外层值，不应把“退出范围”一律理解成清空所有外层状态。

查询路径：在绑定内部打开 scope，再让子任务读取

保存为 RequestContextDemo.java。示例用两个简单子任务代替真实下游调用，专门展示上下文的可见性，没有引入 HTTP 框架或数据库。

import java.util.concurrent.StructuredTaskScope;

public class RequestContextDemo {
    // key 可以全局稳定存在，绑定值只在请求作用域内可见。
    private static final ScopedValue CTX =
            ScopedValue.newInstance();
    record RequestContext(String requestId, String tenantId) {}

    static String handle(RequestContext context) throws Exception {
        // 先绑定，再在绑定内部打开结构化任务作用域。
        return ScopedValue.where(CTX, context).call(() -> {
            try (var scope = StructuredTaskScope.open()) {
                var summary = scope.fork(() -> readPart("summary"));
                var detail = scope.fork(() -> readPart("detail"));
                // 默认策略要求全部成功；失败时不继续读取部分结果。
                scope.join();
                return summary.get() + " | " + detail.get();
            }
        });
    }

    static String readPart(String part) {
        // 子任务读取继承的绑定；不需要把上下文作为每层参数。
        RequestContext context = CTX.get();
        return part + ":" + context.requestId() + ":" + context.tenantId();
    }

    public static void main(String[] args) throws Exception {
        var context = new RequestContext("req-demo", "tenant-demo");
        System.out.println(handle(context));
        // handle 已退出绑定，此处预期为 false。
        System.out.println(CTX.isBound());
    }
}

# 使用 JDK 25 编译和运行；预览开关来自 StructuredTaskScope。
javac --enable-preview --release 25 RequestContextDemo.java
java --enable-preview RequestContextDemo

按代码推导，两个结果中的请求号都应为 req-demo，租户都应为 tenant-demo；最后一次 isBound() 为 false，因为这个示例在进入 handle 前没有外层绑定。这里描述的是示例预期，不是本机执行记录。

关键边界是 StructuredTaskScope.open() 所处的位置。打开任务作用域时会捕获当前 ScopedValue 绑定，scope 派生的子任务继承它。若先在外面打开 scope，再在另一个绑定范围里 fork，就把捕获边界和派生边界错开了，可能触发结构约束异常。把 open、fork、join 和 close 都放进同一个绑定块最直观。

异常处理：读取失败与任务失败分开理解

没有绑定时直接 get() 会抛出 NoSuchElementException。对于强制要求请求上下文的业务方法，这通常说明调用位置越出了约定边界，不宜悄悄补一个默认租户。只有业务本来允许缺省值时，才考虑 orElse 或先检查 isBound()。

示例使用 scope 的默认策略：全部子任务成功后再读取结果；一个子任务失败时，join 会以 StructuredTaskScope.FailedException 报告失败，并取消其他未完成子任务。业务侧可以查看 cause 决定如何返回请求错误。本例让异常向上传递，避免把任务失败伪装成正常拼接结果。

等待也可能受到中断。接口若允许抛出 InterruptedException，可继续向上传递；若在应用边界捕获而不再抛出，要按该边界的中断约定处理，不能吞掉信号后继续组装成功响应。上下文传递与失败策略是两个独立职责，读得到请求号不代表下游调用已经成功。

清理策略：关闭子任务范围，再退出请求绑定

try-with-resources 负责关闭 scope；关闭操作会等待其派生线程结束。取消通常依赖中断协作，因此子任务若不响应中断，关闭也可能长时间等待。ScopedValue 的有界生命周期不等于强制终止任意阻塞代码。

当外层 call 正常返回或因异常退出时，绑定会恢复为进入前的状态，无需自己写 remove。示例没有外层绑定，因此恢复为未绑定；嵌套场景则恢复原来的上下文。这种恢复只解决绑定状态，不会替业务关闭连接、文件或其他资源；那些资源仍由各自的所有权规则管理。

常见问题

CompletableFuture 或普通线程池也会自动继承吗

不能因为提交动作发生在绑定块里就这样假定。本文所述自动继承依赖 StructuredTaskScope 的结构约束。已有异步框架若没有这一约定，可以显式传递不可变上下文，并在任务真正执行时建立自己的绑定；同时明确任务是否允许在请求结束后继续存在。

子任务能把上下文改回父任务吗

ScopedValue 适合向调用层级下方提供上下文。需要子任务产生结果时，像示例一样通过任务返回值汇总；不要用共享可变上下文充当反向结果通道。嵌套重新绑定只改变相应范围看到的值。

只在当前线程调用多个业务方法，是否也要创建 scope

不需要。只用 where 加 call/run 就可以让同一调用范围里的方法读取值。只有需要结构化并发子任务时，才引入本文的 scope 部分和对应的预览配置。

参考资料

• JDK 25 ScopedValue API
• JDK 25 StructuredTaskScope API 与绑定继承
• Oracle：结构化并发使用说明