Java ScopedValue 如何替代跨线程上下文传递

如果你只是想把请求 ID、租户信息或安全身份沿着一串方法调用传下去，Java 25+ 更适合优先考虑 ScopedValue。它不是把值挂在线程上长期保存，而是把值绑定到一次方法执行的动态作用域：作用域结束，绑定自动解除；下游只能读取，不能像 ThreadLocal 那样随意改写。

ScopedValue 的关键不是全局变量，而是动态作用域

先定义一个只在当前类内部使用的 key，再把请求包在绑定范围内。下面的 handle 和 repository 不需要增加 requestId 参数，但它们都能读取同一个请求上下文。

import java.lang.ScopedValue;

final class RequestContext {
    // key 像访问能力一样保存，避免把上下文入口暴露给无关代码
    static final ScopedValue REQUEST_ID = ScopedValue.newInstance();
}

void serve() {
    // run 只覆盖这次调用；正常返回或抛异常都会自动解除绑定
    ScopedValue.where(RequestContext.REQUEST_ID, "req-42")
            .run(this::handle);
}

void handle() {
    // get 读取当前线程最近的一层绑定；未绑定时会抛 NoSuchElementException
    String requestId = RequestContext.REQUEST_ID.get();
    repository(requestId);
}

void repository(String requestId) {
    // 真实业务中这里也可以直接 get；示例保留参数表示数据库调用需要什么
    System.out.println("load for " + requestId);
}

绑定是按线程生效的，但生命周期由 run 或 call 控制。若内部再次使用 where 绑定同一个 key，内层读取新值；内层结束后会恢复外层值。这种“可嵌套但不可泄漏”的行为，正是它替代请求级 ThreadLocal 的核心。

和 ThreadLocal 对比，先看生命周期与写入权限

ThreadLocal 的优势是成熟、通用，而且允许线程内更新；问题也来自这里：线程池线程会复用，忘记 remove() 就可能把上一个请求的值带到下一个请求。ScopedValue 让清理动作成为 API 结构的一部分，并把 key 的持有者限制为能读取它的代码。

迁移时不要把所有 ThreadLocal 全部替换。只读且“由调用者设置、由下游读取”的数据优先迁移；如果下游必须更新值，或者值必须跨越一个脱离父调用的异步任务长期存在，先保留原设计并单独梳理所有权。

跨线程传递要配合结构化任务作用域

常见误区是认为 ScopedValue 会自动进入 ExecutorService 的工作线程。它不会。普通线程或线程池不在这个 API 的结构化继承范围内，任务提交前后的绑定边界必须显式设计。

在 Java 25 中，StructuredTaskScope 仍属于预览 API。按该版本开启预览后，作用域创建时会捕获当前绑定，随后用 fork 建立的子任务可以读取它；父任务也要等待并关闭任务作用域，避免父绑定已经恢复而子任务还在运行。

ScopedValue.where(RequestContext.REQUEST_ID, "req-42").run(() -> {
    // StructuredTaskScope 在 Java 25 仍需按对应版本开启 preview
    try (var scope = StructuredTaskScope.open()) {
        scope.fork(() -> {
            // 结构化子任务继承创建 scope 时的 REQUEST_ID
            audit(RequestContext.REQUEST_ID.get());
            return null;
        });
        scope.join(); // 等待子任务结束，保证绑定生命周期覆盖任务
    } catch (InterruptedException e) {
        // 中断要恢复线程标记，交给上层决定取消策略
        Thread.currentThread().interrupt();
        throw new IllegalStateException("task interrupted", e);
    }
});

迁移前后的四项检查

1. 确认运行基线。使用 Java 25+ 编译正式 ScopedValue API；不要把旧版本 preview 示例原样复制到生产代码。
2. 确认对象可共享。跨线程继承的值最好是不可变对象；可变对象必须自行同步。
3. 确认未绑定分支。可选上下文用 isBound() 或 orElse，强制上下文才调用 get()。
4. 确认异步边界。把任务提交到普通线程池前，明确是传参、任务包装，还是改用结构化任务；不要凭“看起来在线程里”判断可见性。

一句话判断：ScopedValue 适合“调用者设定一次、调用链只读使用、离开作用域就失效”的上下文；ThreadLocal 仍适合必须可变或受旧框架约束的线程状态。两者的选择关键不在 API 新旧，而在生命周期和所有权是否匹配。

常见问题

ScopedValue 能完全替代 ThreadLocal 吗？

不能。它主要替代只读、短生命周期的隐式参数，不负责覆盖所有线程本地状态。

为什么在线程池里读取不到 ScopedValue？

因为普通线程池不是结构化继承边界。请改为显式传递上下文，或使用支持结构化子任务的方案。

get() 没有绑定时怎么办？

强制场景保留 get() 让错误尽早暴露；可选场景用 isBound() 或 orElse(defaultValue)。

资料：Oracle Java SE 25 ScopedValue API 与 Scoped Values 开发指南，StructuredTaskScope API 仅用于说明结构化继承边界。