Java ScopedValue怎样向嵌套任务传递只读上下文

在请求链里，requestId、租户标识、审计主体这类信息经常需要从入口传到很深的服务方法。Java 25 的 ScopedValue 可以把它们绑定到一个动态作用域中，调用链里的方法直接读取；如果再配合 StructuredTaskScope，由结构化任务创建的子任务也能继承同一份上下文。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/ScopedValue.html

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

最稳妥的做法是：用不可变 record 组合请求上下文，只绑定一个 ScopedValue，在它的 where(...).call(...) 作用域内创建并关闭结构化任务。这样嵌套任务能读到上下文，外层操作结束后绑定也会自动恢复。

• ScopedValue 负责“在哪个动态作用域内可读”。
• StructuredTaskScope 负责“哪些结构化子任务可以继承”。
• 跨线程共享的值应当不可变，任务边界必须用 join 和 close 收拢。

先理解 ScopedValue 的作用域

ScopedValue 不是一个可以随时修改的全局变量。它更像一个只读的隐式参数：入口通过 where 建立绑定，直接或间接调用的方法通过同一个 key 调用 get() 读取。外层操作正常返回或抛出异常后，绑定会恢复为未绑定状态。

把 key 定义为私有静态字段，可以把访问能力限制在需要它的类或嵌套范围内。读取未绑定的值会抛出异常，因此不确定是否存在上下文时，可以使用 isBound() 或 orElse。

用不可变对象承载一组上下文

如果需要传递 requestId、tenantId 和调用来源，不建议为每个字段创建一个独立的 ScopedValue。官方 API 文档说明它有较小的线程缓存，应用应尽量减少绑定数量；把相关字段放进一个不可变 record，再绑定一次更清晰。

import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;

public class ScopedValueDemo {
    // key 是访问上下文的能力，不把它暴露给不相关的组件
    private static final ScopedValue CONTEXT = ScopedValue.newInstance();

    // record 保证示例中的请求上下文创建后不再修改
    record RequestContext(String requestId, String tenantId) {}

    static String loadUser() {
        // 深层方法不必继续声明 requestId 和 tenantId 参数
        var context = CONTEXT.get();
        return "用户查询：" + context.tenantId();
    }

    static String loadOrder() {
        // 只读取当前线程动态作用域里的同一份上下文
        var context = CONTEXT.get();
        return "订单查询：" + context.requestId();
    }

    static String handle() throws InterruptedException {
        // try-with-resources 确保子任务完成后关闭结构化作用域
        try (var scope = StructuredTaskScope.open()) {
            Subtask user = scope.fork(ScopedValueDemo::loadUser);
            Subtask order = scope.fork(ScopedValueDemo::loadOrder);

            // join 等待子任务结束，close 不会让未结束的子任务逃出作用域
            scope.join();
            return user.get() + "；" + order.get();
        }
    }

    public static void main(String[] args) throws Exception {
        var context = new RequestContext("req-1001", "tenant-a");

        // call 只在这段操作期间绑定上下文，完成后自动恢复
        String result = ScopedValue.where(CONTEXT, context)
                .call(ScopedValueDemo::handle);
        System.out.println(result);
    }
}

这个示例把绑定放在创建任务之前，所以两个 fork 出来的子任务都能读取 CONTEXT。Java 25 中 ScopedValue 是正式 API，而 StructuredTaskScope 仍属于预览 API，编译和运行时需要打开预览特性：

# Java 25 的 StructuredTaskScope 是预览 API，编译时开启预览特性
javac --enable-preview --release 25 ScopedValueDemo.java

# 运行时也要开启相同的预览特性
java --enable-preview ScopedValueDemo

让嵌套任务继承同一份上下文

继承不是普通线程池里的任意线程复制。结构化任务在打开 scope 时捕获当前线程的 scoped-value 绑定，随后由该 scope 创建的子任务继承这些绑定。子任务内部还可以继续打开新的 scope，新的子任务会继承它打开时可见的绑定，因此形成一棵受父子生命周期约束的任务树。

重要顺序是“先绑定，再打开 scope，再 fork”。如果在 scope 创建后改变当前绑定，运行时会检查 fork 时的绑定是否仍与创建 scope 时一致，避免子任务拿到一个即将失效的上下文。

重绑定只影响内层作用域

业务中可能需要在一个子操作里临时切换租户或审计标签。ScopedValue 支持嵌套重绑定，但它不会修改外层对象；内层 where 结束后，读取结果回到外层绑定。

static void nestedOperation() {
    var outer = CONTEXT.get();

    // 仅在内层操作中临时使用新的不可变上下文
    var inner = new RequestContext(outer.requestId(), "tenant-b");
    ScopedValue.where(CONTEXT, inner).run(() -> {
        System.out.println("内层租户：" + CONTEXT.get().tenantId());
    });

    // 内层 run 结束后自动回到外层绑定
    System.out.println("外层租户：" + CONTEXT.get().tenantId());
}

这也是它和 ThreadLocal 的关键区别之一：ThreadLocal 的值可以被远处代码改写，并且如果忘记清理，值可能在线程复用期间继续存在；ScopedValue 的生命周期由调用结构限定，更适合单向传递只读数据。

出现问题时按这份清单排查

常见问题

ScopedValue 能替代所有 ThreadLocal 吗？

不能。它主要解决“调用链和结构化子任务只读共享”的问题。如果代码确实需要在线程生命周期内维护可变状态，仍需重新评估 ThreadLocal 或显式参数；不要为了少写参数而隐藏可变依赖。

为什么不直接把上下文作为方法参数传下去？

显式参数通常更容易测试和追踪。ScopedValue 适合参数会穿过很多中间层、但只有远端回调真正使用的场景。选择它时应把 key 的可见范围、上下文不可变性和任务生命周期一起设计。

归纳起来，Java ScopedValue 的重点不是“把变量放到线程里”，而是把只读数据放进一个有边界的动态作用域；StructuredTaskScope 再把这个边界安全地延伸到嵌套任务。只要坚持不可变上下文、绑定先于建 scope、任务在 scope 内完成这三个条件，代码就能同时保持上下文可达和生命周期可控。