Java ScopedValue 怎么在线程调用链传递上下文

ScopedValue 适合把请求 ID、租户信息等“入口确定、下游只读”的上下文传到深层方法。做法是在入口用 ScopedValue.where(KEY, value).run(...) 建立动态作用域，调用链中持有同一个 KEY 的代码可用 get() 读取；操作正常结束或抛出异常后，绑定都会自动撤销。

• ScopedValue 从 Java 25 起成为正式 API。
• 绑定按线程生效，适合单向传递，不是任意线程间的全局变量。
• 值若要被多个结构化子任务共享，应使用不可变对象或自行同步。

把上下文绑定在请求入口

KEY 通常声明为访问范围尽可能小的 private static final 字段。它既是读取值的键，也像一种能力：只有能访问该 KEY 的代码才能读取对应上下文。

public final class RequestContextHolder {
    private static final ScopedValue CONTEXT =
            ScopedValue.newInstance();

    public record RequestContext(String traceId, String tenantId) {}

    public static void handle(String traceId, String tenantId) {
        var context = new RequestContext(traceId, tenantId);
        ScopedValue.where(CONTEXT, context).run(() -> dispatch());
        // run 返回后，当前线程中的绑定自动撤销
    }

    private static void dispatch() {
        service(); // 中间方法不需要增加上下文参数
    }

    private static void service() {
        var context = CONTEXT.orElseThrow(
                () -> new IllegalStateException("缺少请求上下文"));
        audit(context.traceId(), context.tenantId()); // 深层调用读取只读上下文
    }

    private static void audit(String traceId, String tenantId) {
        // 这里接入业务审计逻辑，示例省略具体存储
    }
}

为什么它比 ThreadLocal 更适合单向上下文

ThreadLocal 可以在任意下游调用 set，生命周期也可能超过一次请求，在线程池中忘记 remove 就容易串值。ScopedValue 的绑定只覆盖 run 或 call 的执行范围，下游只能读取；需要临时覆盖时只能创建嵌套作用域，退出后自动恢复外层值。

跨线程时要看是否属于结构化子任务

绑定本身是线程级的，随手创建普通线程或提交到普通线程池，不应假设上下文会自动出现。官方支持的继承场景是 StructuredTaskScope：打开作用域时捕获的 ScopedValue 绑定，会被该作用域通过 fork 创建的子任务继承。Java 26 中 StructuredTaskScope 仍带预览标记，使用前要按对应 JDK 的预览规则编译和运行。

上线前检查这些边界

不要为每个字段创建大量 ScopedValue，优先绑定一个小型不可变上下文对象。读取可能发生在作用域外时，用 isBound()、orElse() 或 orElseThrow() 明确缺失策略；直接 get() 在未绑定时会抛出 NoSuchElementException。如果下游需要修改值，应该返回新结果或建立嵌套绑定，而不是把可变容器塞进上下文。

常见问题

ScopedValue 可以完全替代 ThreadLocal 吗？

不能。它优先解决有界、单向、只读的上下文传递；需要长期可变的线程局部状态时，仍要根据场景评估 ThreadLocal。

嵌套绑定会覆盖外层值吗？

只在内层 run 或 call 执行期间读取到新值，内层结束后会恢复外层绑定，不需要手工回滚。