ScopedValue是Java21引入的不可变、作用域限定的数据载体，专为虚拟线程设计，通过栈帧绑定、自动清理和不可变性，彻底规避ThreadLocal的内存泄漏、数据污染与性能开销。
ScopedValue 不是 ThreadLocal 的平替，而是针对虚拟线程与结构化并发重新设计的上下文传递机制——它用“作用域生命周期”代替“线程生命周期”，从根本上规避内存泄漏、数据污染和哈希查找开销。
为什么 ScopedValue 能真正替代 ThreadLocal
ThreadLocal 在百万级虚拟线程场景下会引发三重压力：每个线程持有一份副本，堆内存持续增长；频繁 GC 扫描大量弱引用条目；线程卸载时需同步状态，隐式拖慢调度。而 ScopedValue 将值绑定到执行栈帧，仅在 where().run() 块内存在，退出即释放，不依赖线程身份，也不保留强引用。
- 读取性能约 3ns/次，比 ThreadLocal 的 15ns 快 5 倍以上
- 无哈希表、无 ThreadLocalMap、无 remove() 手动清理义务
- 值不可变 + 作用域封闭 → 天然避免并发篡改与跨请求串号
正确声明与绑定方式
ScopedValue 实例必须声明为 static final，仅作类型标识；真实绑定必须发生在明确的作用域内，不能提前 set 或全局初始化。
- ✅ 正确：在 Filter 或 WebMvc Handler 中调用
ScopedValue.where(TRACE_ID, header).run(() -> handle(request)) - ❌ 错误：在 Spring Bean 构造器中调用
TRACE_ID.set("xxx")→ 抛IllegalStateException: not in scope - ❌ 错误：在作用域外调用
get()→ 返回 null（不抛异常），但下游逻辑可能因空值出错
异步与并行场景下的关键约束
ScopedValue 默认不跨线程传播，这是设计使然，不是缺陷。CompletableFuture、ForkJoinPool、并行 Stream 或自定义线程池中的任务，都无法自动继承父作用域值。
- 在
supplyAsync()内部需手动重建：用ScopedValue.where(...).run(...)显式绑定 - 并行流中每个
forEach元素应单独绑定折扣上下文，防止不同订单混用同一用户折扣 - Spring AOP 若启用异步切面（如
@Async），切面内部必须重绑，否则 MDC 日志丢失 traceId
哪些情况仍需保留 ThreadLocal
并非所有 ThreadLocal 使用点都可无脑替换。以下三类需谨慎评估：
- 第三方库强依赖 ThreadLocal（如部分 JDBC 驱动的连接上下文），你无法修改其源码
- 需要跨作用域“泄漏”的全局计数器或统计指标，ScopedValue 明确禁止此类共享
- 需兼容 JDK 20 及更早版本的项目，因 ScopedValue 是 JDK 21 预览特性，需启动参数
--enable-preview
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
