Java 25 ScopedValue 替代 ThreadLocal：虚拟线程里的请求上下文怎么传

订单服务切到虚拟线程后，最容易被忽略的不是线程数量，而是请求上下文怎么跟着调用链走。比如日志需要带上 requestId 和租户编号，旧代码常用 ThreadLocal；但当数据只应该在一次调用范围内可读时，Java 25 的 ScopedValue 更贴合这个语义。

一句话判断：只读、短生命周期、由外层调用方绑定的请求上下文，可以优先考虑 ScopedValue；需要在线程内部反复修改，或依赖线程池任务复用语义的状态，仍应保留明确的参数传递或谨慎使用 ThreadLocal。

Java 25 为什么把请求上下文单独做成 ScopedValue

OpenJDK 25 把 JEP 506 的 Scoped Values 纳入正式平台能力。它解决的不是“再造一个全局变量”，而是把一个值绑定到明确的调用范围：绑定开始后，当前方法以及它调用到的下层代码都能读取；范围结束，绑定自然失效。

这和请求日志里的 requestId 场景很匹配。入口拿到值，认证、订单查询和日志组件都只读它，响应返回后不应继续留在执行环境里。这个方案比“先写入，再记得 finally 清空”的人工约定更可靠。

先看一段能运行的最小写法

下面的示例不依赖 Spring，直接用 JDK 25 编译运行。REQUEST_ID 和 TENANT 是两个不对外暴露的私有键，入口在调用链外层绑定对应的值：

import java.util.concurrent.StructuredTaskScope;

public class ScopedContextDemo {
    private static final ScopedValue REQUEST_ID = ScopedValue.newInstance();
    private static final ScopedValue TENANT = ScopedValue.newInstance();

    static String loadOrder(String orderId) {
        return "request=" + REQUEST_ID.get()
                + ", tenant=" + TENANT.get()
                + ", order=" + orderId;
    }

    public static void main(String[] args) throws Exception {
        var result = ScopedValue.where(REQUEST_ID, "req-7f31")
                .where(TENANT, "tenant-east")
                .call(() -> loadOrder("A-1024"));
        System.out.println(result);
    }
}

运行结果应包含 request=req-7f31、tenant=tenant-east 和订单号。注意 get() 只能在绑定范围内读取；如果只是想提供兜底值，可以用 orElse("anonymous")，不要在业务逻辑里到处捕获未绑定异常。

把它放进虚拟线程调用链时，边界在哪里

虚拟线程让阻塞式 I/O 的并发模型更轻量，但上下文传递仍然需要一个清楚的边界。可以把绑定操作放在请求入口，再让下层方法只负责读取即可：

static String handle(String tenant, String requestId) throws Exception {
    return ScopedValue.where(TENANT, tenant)
            .where(REQUEST_ID, requestId)
            .call(() -> {
                log("start");
                return queryInventory();
            });
}

static String queryInventory() {
    log("query inventory");
    return "ok";
}

static void log(String message) {
    System.out.println(REQUEST_ID.orElse("no-request") + " " + message);
}

如果调用链继续创建子任务，优先使用结构化并发，让任务的生命周期仍然落在请求范围内。示例中的 StructuredTaskScope 在不同 JDK 版本可能仍有预览特征，生产项目要按实际编译参数和框架支持情况确认，不要只看到 API 名称就直接复制到旧版本环境里。

ScopedValue 和 ThreadLocal，别只看“谁更现代”

因此迁移不是全局替换。一个鉴权结果如果在请求开始后保持不变，很适合做成不可变对象绑定到 ScopedValue；一个需要在多个阶段累积统计值的对象，直接替换后反而会让代码逻辑变绕，可以先保留显式参数传递的写法。

从 ThreadLocal 迁移前，先做这四个检查

检查一：下层代码是否只需要读取

搜索 set、remove 和包装对象的写入方法。如果业务在深层方法里修改上下文，再换成 ScopedValue 会破坏原有语义。先把“读”和“写”逻辑拆开，通常比直接改类型更省时间。

检查二：上下文是否有明确的入口和出口

HTTP 过滤器、RPC 拦截器或消息消费入口都可以成为绑定点。不要在工具类的静态方法里偷偷绑定，否则调用关系会变得难以复查。

检查三：异步任务是否仍在请求范围内

把后台任务丢到一个长期存活的线程池后，不能假设它永远拥有原请求上下文。要么把必要字段变成任务参数，要么让任务在明确的作用域里启动并等待结果。

检查四：测试是否覆盖“范围结束后不可读”

除了验证绑定期间能读到值，还要写一个范围结束后的测试，确认代码没有把上下文泄漏到下一次请求。这个测试比单纯检查日志字符串更能抓住迁移错误。

Java 25 ScopedValue 的采用风险与最小落地路径

第一步只改一个内部调用链，例如订单查询的日志上下文；第二步把 requestId、租户编号和权限快照整理成不可变字段；第三步再观察虚拟线程、线程池和框架拦截器之间的交接点。每一步都保留一条旧路径，出现兼容问题时可以快速回退。

还要留意键对象的可见范围。ScopedValue 的安全使用依赖访问控制，不要把键公开成任何模块都能随意绑定的公共常量。对外部扩展点，显式参数往往更容易审计。

相关问题

ScopedValue 能存放可变对象吗？

类型上可以，但不建议把它当作可变共享容器。绑定的是对象引用，不会自动冻结对象；如果需要稳定上下文，优先使用不可变记录或只读快照。

ThreadLocal 应该马上全部替换吗？

不用。只读、范围明确的请求数据适合迁移；线程内缓存、兼容旧框架的局部状态和确实需要更新的数据，应先评估调用链再决定。

没有绑定值时怎么避免异常？

对可选上下文使用 orElse 提供默认值；对必须存在的 requestId，保留 get() 让测试尽早暴露入口漏绑问题。

最后的判断

Java 25 的 ScopedValue 适合表达“外层设置一次、下层一路读取、调用结束就失效”的请求信息。把它和虚拟线程一起使用时，关键不是追逐新 API，而是先把上下文的写入权限、任务边界和回退路径梳理清楚。能满足这三个条件，再从一个小调用链开始迁移，通常比全项目替换更稳妥。