Java ScopedValue 如何替代只读 ThreadLocal 上下文

如果请求标识、租户编号或只读权限上下文要穿过多层 Java 方法，逐层增加参数会让接口变得臃肿；继续使用可变 ThreadLocal，又容易在复用线程上留下超出请求生命周期的状态。Java 25 的 ScopedValue 更适合这类“单向传递、作用域内只读”的场景：在入口建立绑定，深层方法读取，作用域结束后自动恢复。

先划清 ScopedValue 与 ThreadLocal 的适用边界

ThreadLocal 允许深层调用读取上下文，也允许远处的代码重新设置值；如果清理遗漏，线程池中的下一次请求可能继续看到旧状态。ScopedValue 则把值绑定在一次 run 或 call 的动态作用域中，调用正常返回或抛出异常后，绑定会恢复为未绑定或外层旧值。

因此，先不要把所有 ThreadLocal 全部替换。只读请求上下文、追踪信息和不可变租户配置适合迁移；线程绑定的可变缓存、必须由深层代码更新的状态，仍要重新评估。

用不可变上下文替换可变线程槽位

迁移时把零散字段收拢为不可变记录，并把 ScopedValue 作为私有访问能力。下面的示例只展示结构关系，重点是绑定点和读取点，而不是把上下文重新做成全局可写变量。

import java.util.concurrent.Callable;

// 把一次请求内不会改变的信息集中到不可变对象中
record RequestContext(String requestId, String tenantId) {}

final class RequestScope {
    // 只暴露键，不把可变的 ThreadLocal 槽位交给深层代码
    private static final ScopedValue CONTEXT = ScopedValue.newInstance();

    static  T execute(RequestContext context, Callable action) throws Exception {
        // 绑定只覆盖 action 的动态作用域，退出后自动恢复
        return ScopedValue.where(CONTEXT, context).call(action::call);
    }

    static String currentTenant() {
        // 未绑定时立即暴露调用边界错误，不静默读取旧请求数据
        return CONTEXT.orElseThrow(() -> new IllegalStateException("缺少请求上下文")).tenantId();
    }
}

入口可以调用 RequestScope.execute(new RequestContext("req-17", "tenant-a"), service::load)，而 service 下方的方法只调用 RequestScope.currentTenant()。实际项目中应把键放在限制访问的类或嵌套类中，避免任何组件都能随意重新绑定。

处理嵌套绑定与结构化并发边界

ScopedValue 支持嵌套重新绑定。例如外层租户为 tenant-a 时，某个内部操作可以暂时绑定 tenant-b；内层操作结束后读取结果会回到 tenant-a。这个特性适合明确的临时覆盖，不适合把可变业务状态偷偷塞进调用链。

跨线程时也要看任务结构。Java API 文档说明，使用 StructuredTaskScope 时，打开作用域会捕获当前绑定，随后 fork 的子任务可以继承它；共享的上下文对象必须不可变，或由同步机制保护。普通线程池异步提交不能因此自动获得同样的语义，迁移时要把任务的创建、等待和结束边界一起看。

用判断清单完成迁移

• 数据是否只需要从入口向深层读取，而不需要被深层代码修改？是，优先评估 ScopedValue。
• 数据是否必须在一次调用返回后继续存在？是，ScopedValue 不是合适的持久存储。
• 是否会把同一个对象交给多个子任务？是，先使用不可变对象，或明确同步策略。
• 是否依赖线程池中一个任务更新状态、下一个任务继续读取？是，先保留原模型并补齐清理与测试。

最终的迁移目标不是把 API 名称换掉，而是让上下文的所有权和生命周期可读：谁建立绑定、哪些方法只能读取、何时恢复，以及哪些子任务允许继承，都应该能从代码结构中看出来。

常见问题

ScopedValue 能完全替代 ThreadLocal 吗？

不能。它主要替代只读、短生命周期、沿调用链传递的上下文；需要可变线程状态或非结构化生命周期的场景仍需单独设计。

ScopedValue 未绑定时调用 get 会怎样？

get() 会抛出未绑定异常。可以用 isBound()、orElse() 或 orElseThrow() 把缺少上下文的策略写清楚。

为什么示例把多个字段放进一个 record？

ScopedValue 的缓存规模有限，少量绑定更容易维护；不可变 record 还能避免子任务之间共享可变对象。