Java 25 ScopedValue 怎么替代 ThreadLocal：请求上下文的边界与并发验收

把 traceId、租户号或当前用户一路塞进 Java 方法参数，代码很快会变得啰嗦；把它们放进 ThreadLocal，又容易忘记清理，在线程池复用时留下串请求风险。Java 25 提供的 ScopedValue 更适合“只读、单向、只在一段调用范围内可见”的请求上下文，但它不是 ThreadLocal 的无脑替换。

如果上下文只需要从调用方传给当前调用链及其结构化子任务，并且绑定值不会被修改，优先考虑 ScopedValue；需要在线程生命周期内反复改写状态时，仍应重新评估 ThreadLocal 或显式参数。

先把 ThreadLocal 的问题边界说清楚

ThreadLocal 解决的是“每个线程有一份独立值”。这在老式线程模型里很实用，但它的值没有天然的语法边界：调用链结束后，如果忘记 remove()，线程池里的下一次请求仍可能看到旧值；如果代码深处可以随意 set()，调用方也很难判断谁改过上下文。

ScopedValue 的目标不同。OpenJDK JEP 506 把它描述为一种在动态作用域内共享不可变数据的方式，绑定由调用方建立，读取方只能在绑定范围内读取。这里的关键不是“少写一个参数”，而是让生命周期能直接从代码结构中看出来。

用一个请求上下文替换单向 ThreadLocal 传递

下面的示例把 traceId 和租户号封装成不可变 record。业务方法不需要层层接收这两个参数，但只有持有 REQUEST 引用的代码才能读取它。

import java.util.concurrent.StructuredTaskScope;

record RequestContext(String traceId, String tenantId) {}

final class RequestContextDemo {
    private static final ScopedValue REQUEST = ScopedValue.newInstance();

    static String loadProfile() {
        return REQUEST.get().tenantId() + ":profile";
    }

    static String handle(String traceId, String tenantId) {
        var context = new RequestContext(traceId, tenantId);
        return ScopedValue.where(REQUEST, context).call(() -> loadProfile());
    }
}

这里有两个容易忽略的细节。第一，orElse 只能提供缺省读取结果，不能把“没有绑定”伪装成一个合法请求；关键链路更适合直接用 get()，让缺失上下文尽早暴露。第二，record 只是让外层引用不可重新指向，record 内部字段也应使用不可变类型，不能把可变集合塞进去后再从别处修改。

从旧代码迁移时，逐项对照这张变更表

不要因为上下文“看起来像全局变量”就全部替换。比如请求计数器、可变缓存、需要在多个阶段反复更新的对象，都不属于 ScopedValue 的理想场景；把这些对象塞进一个 record 并不会自动获得线程安全。

并发读取时，绑定会怎样传给子任务

Java SE 25 的 StructuredTaskScope API 规定：创建 scope 时捕获当前线程的 scoped value 绑定，之后通过 fork 创建的子任务可以读取这份绑定。父任务在 scope 关闭前不会越过绑定边界，因此不会出现父调用已经结束、子任务还在读取已恢复值的情况。

static String aggregate(String traceId, String tenantId) throws Exception {
    var context = new RequestContext(traceId, tenantId);
    return ScopedValue.where(REQUEST, context).call(() -> {
        try (var scope = StructuredTaskScope.open()) {
            var profile = scope.fork(RequestContextDemo::loadProfile);
            var quota = scope.fork(() -> REQUEST.get().tenantId() + ":quota");
            scope.join();
            return profile.get() + "|" + quota.get();
        }
    });
}

这段代码的验收重点有三个：两个子任务都读到同一 tenantId；子任务完成前 scope 不提前关闭；共享的 RequestContext 没有可变字段。若任务需要修改上下文，应改成显式返回结果，在父任务中合并，而不是让多个线程争抢一个可变对象。

Java 25 的预览开关要单独做回归

ScopedValue 在 JDK 25 已正式交付，但 StructuredTaskScope 仍是预览 API。只要示例或业务代码调用了后者，编译和运行都应明确打开预览特性，不能把本地 IDE 的隐式配置当成发布配置。

javac --release 25 --enable-preview RequestContextDemo.java
java --enable-preview RequestContextDemo

上线前至少做四组检查：未绑定时确认读取路径会按预期失败；嵌套 where 后确认内层值只在内层生效；子任务完成后确认父任务仍能读取原绑定；异常和超时路径确认 try-with-resources 能关闭 scope。对于仍处于预览阶段的 API，还要把 JDK 小版本升级列入兼容测试，而不是只测一次编译。

常见问题

ScopedValue 能完全替代 ThreadLocal 吗？

不能。它主要替代单向传递且生命周期受调用范围约束的上下文；需要可变线程状态或稳定 API 兼容时，应保留原方案或改用显式参数。

ScopedValue 绑定的对象必须是不可变的吗？

跨线程共享时应使用不可变对象，或自行提供可靠同步。把可变 Map 放进 ScopedValue 并不会让 Map 变成线程安全。

StructuredTaskScope 在 Java 25 能直接用于生产吗？

它在 Java 25 仍是预览 API，必须显式启用预览特性，并把编译、运行、升级和回滚配置一起纳入验收。

为什么退出 where 代码块后读不到值？

这是设计结果。绑定只覆盖 run 或 call 的动态范围；需要更长生命周期的数据，应显式传参或重新设计调用边界。

迁移清单

• 先确认数据是只读请求上下文，而不是隐式共享的可变状态。
• 用不可变 record 表达上下文，避免在子任务中修改它。
• 为未绑定、嵌套绑定、异常退出和并发继承分别写测试。
• 若使用 StructuredTaskScope，锁定 Java 25 的预览编译与运行参数。

ScopedValue 的价值在于把“谁能看到这份上下文、看到多久”变成可读的代码边界。迁移时先守住这个边界，再考虑减少参数传递，效果通常比一次性替换所有 ThreadLocal 更稳。