最近组里讨论得最凶的一个技术话题就是这个标题别再用 ThreadLocal 了ScopedValue 更香ThreadLocal 在 Java 生态里扎根太深了业务上下文、请求变量、事务状态、日志 traceId哪哪都有它。我第一次看到 ScopedValue 的时候第一反应也是“又一个替代品”但把 JEP 429 到 JEP 485 的演进、和虚拟线程配合的场景看完再自己写了几轮对比代码之后我承认在相当大一部分场景里ScopedValue 确实比 ThreadLocal 更合适而且是那种“设计上就更对”的合适。这篇不是来劝你删光 ThreadLocal 的那也不现实——框架里、旧代码里到处都是。我想做的是把 ThreadLocal 的几个硬伤、ScopedValue 的底层设计逻辑、实操 API、以及从 ThreadLocal 迁移到 ScopedValue 的完整案例一次性讲透。Java 21 以上的项目可以开始练手转正后的新版本就能正式上生产了。不管是刚上手虚拟线程的同学还是被线程池脏数据坑过无数次的老人这篇应该都有你能用得上的东西。1. ThreadLocal 不是原罪但几个硬伤确实让人头疼1.1 线程池复用脏数据的重灾区先说最经典的线程池脏数据问题。ThreadLocal 的语义是“每个线程一份变量”它在普通线程场景下非常自然线程死了值就没了。但线上谁不用线程池一旦线程被池化复用问题就来了。举个例子你用固定线程池接收一批任务任务 A 执行的时候在 ThreadLocal 里 set 了一个租户 IDprivate static final ThreadLocalString TENANT new ThreadLocal(); // 任务 A TENANT.set(tenant-a); doBiz(); // 任务 B碰巧被同一个池线程执行 String tenant TENANT.get(); // 拿到的是 task-a 的 tenant-a这还不是最可怕的。最可怕的是任务 A 里如果忘写了 finally remove任务 B 会带着 A 的上下文继续跑。订单信息串到另一个用户头上traceId 串到另一个请求里这类事故在网关、调度中心、MQ 消费端特别常见。你当然可以说“set 之后 finally remove 不就行了”。对规范做法就是 try/finallyTENANT.set(tenant-a); try { doBiz(); } finally { TENANT.remove(); }但人不是机器多写几层嵌套、一个异常路径没覆盖到脏数据就漏出去了。每次 review 代码都要专门盯这些 try/finally这种心智负担本身就是 ThreadLocal 设计上的隐疾。ScopedValue 在 JDK 层面就把“值跟着代码块走、退出自动消失”这件事件内置了也就是后文会讲的结构化绑定。1.2 InheritableThreadLocal继承只有“一次性”线程池照样没戏有人会说ThreadLocal 不是有 InheritableThreadLocal 吗它确实能在创建子线程时把父线程的值复制过去private static final InheritableThreadLocalString CTX new InheritableThreadLocal(); CTX.set(parent-value); Thread child new Thread(() - System.out.println(CTX.get())); // parent-value看起来挺美好但这个“继承”只发生在 new Thread 的那一刻。线程池里的线程是提前创建好的根本不会因为你提交一个任务就重新“继承”所以 InheritableThreadLocal 在线程池面前和普通 ThreadLocal 一样无能为力。另一个问题是InheritableThreadLocal 在虚拟线程大规模普及之后会更尴尬。虚拟线程的特点就是“廉价、量大”如果每个请求都 new 一个虚拟线程每次都把父线程的 ThreadLocal 全量复制一遍内存和 GC 压力都不小。更别说你为了在线程池里传值可能还得引阿里的 TransmittableThreadLocal 这种第三方方案每次提交任务前包一层装饰器侵入性不小。1.3 内存泄漏不是玄学是机制决定的ThreadLocal 的内存泄漏问题我见过太多团队踩坑。简单讲一下机制Thread 对象内部有一个 ThreadLocalMapMap 的 key 是 ThreadLocal 实例但 key 是弱引用value 却是强引用。这里有个非常容易绕晕的点很多人以为“key 是弱引用所以不会泄漏”。实际上泄漏的是 value。key 一旦被回收value 照样挂在 ThreadLocalMap 里只要线程对象还活着value 就不可达也无法回收。线程池线程是长期存活的如果每次都往 ThreadLocal 里塞大的对象又不 remove内存就会一点一点涨上去。容器线程比如 Tomcat 的工作线程尤其危险一天两天看不出来压测跑一夜准崩。你可能会说 value 不就是在线程里用一下吗对但“用一下”不等于“被移除”。ThreadLocalMap 的清理逻辑依赖后续的 get/set 操作去顺带清掉过期 Entry如果某个 key 之后再也没被访问那个 value 就永远不会被清理。ScopedValue 从设计上就绕开了这个问题绑定发生在作用域入口离开作用域整个绑定结构都可以被回收开发者不需要手动 remove也没有“忘了 remove”的选项。1.4 最容易被忽略的ThreadLocal 的可变性和组合性除了脏数据、继承、内存还有一点我是在写框架层代码时体会到的ThreadLocal 是“可写”的。今天 set 进去明天可能在业务深处被改掉后天又有代码判断要不要回滚。可写意味着没有任何机制能保证你拿到的上下文是某个时刻的快照排查问题时很难确认某个值到底是谁在哪一行改的。组合性也差。你想同时传 userId、tenantId、requestId通常要么搞一个包一切的 Context 对象要么写三个 ThreadLocal。写三个的时候set/get/remove 都要重复操作还容易漏一个写一个 Context 对象Context 本身又变成可变共享体子线程改一下父线程就感知了。不是说 ThreadLocal 就一无是处它的简单、灵活、生态兼容是几十年沉淀下来的。我只是想说它并不是没有代价只是这些年大家习惯了这些代价。ScopedValue 的“不可变 结构化 按需可见”正好是冲着这些代价去的。2. ScopedValue 的底层逻辑为什么敢说“更香”2.1 从 JEP 429 到 JEP 485一条不算短的转正之路ScopedValue 不是突然冒出来的新玩具。它和虚拟线程、结构化并发属于同一个大的技术方向也就是 Project Loom 家族。从 JDK 21 的 JEP 429 孵化器版本起步中间经历了 JDK 22、JDK 23、JDK 24 的多轮 Preview最后在 JDK 25 通过 JEP 485 正式转正。为什么在预览里待了这么久因为它的底层实现跟 JVM 运行时有关系不是简单加个类就行。要保证它在 Java 版本升级中稳定、高效、不破坏现有安全模型需要时间打磨。不过好消息是核心 API 从孵化器版本开始就基本定型ScopedValue.newInstance()创建键ScopedValue.where(KEY, value).run(...)绑定并执行KEY.get()读取。后面改的主要是内部实现和边界情形。2.2 三个设计关键词不可变、结构化、按需可见要理解 ScopedValue抓住三个词就够了。第一个词是“不可变”。绑定进去的值在作用域内只能读不能改。想传新值重新开一个作用域重新绑定。这个特性从根本上消除了“值被悄悄篡改”的问题开发者不需要担心上下文被别人 set 坏。第二个词是“结构化”。绑定跟代码块绑定进入run(...)就有值退出就消失跟方法调用栈是同生共死的关系。它不需要你手动 remove也没有线程池复用的残留问题。第三个词是“按需可见”。它不是全局可见的只在绑定的作用域以及该作用域内创建的子任务里可见。比起“每个线程都有完整副本”这种“链路内可见”的表达更精确。你用 ThreadLocal 时是整个线程都有这份值线程池里串了就抓瞎ScopedValue 是跟着调用链走的调用链断了值就没了这是语义级的差别。2.3 ScopedValue vs ThreadLocal一张表看懂差异我把两者最核心的差异整理成了表后面写代码前先过一遍这张表思路会清楚很多维度ThreadLocalScopedValue绑定值是否可变可写可改不可变只能读取生命周期跟随线程需手动 remove跟随作用域代码块自动结束线程池复用脏数据高风险不会串但需在任务内重新绑定子线程/虚拟线程继承默认不继承InheritableThreadLocal 仅创建时复制结构化继承按作用域传播未绑定时的行为get() 返回 null抛 NoSuchElementException绑定 null可以直接抛 NullPointerException清理机制依赖手动 remove可能内存泄漏随作用域结束自然回收引入方式JDK 1.2 就有JDK 21经历孵化/预览新版本转正2.4 对虚拟线程和结构化并发友好的深层原因ThreadLocal 的底层是 Thread 对象里挂一个 ThreadLocalMap存取要做哈希探测。单个线程时还好但虚拟线程场景下假设你要起十万个虚拟线程每个线程都要持有各自的 ThreadLocalMapMap 里有多少 ThreadLocal key 就要有多少 Entry内存开销是非常可观的。ScopedValue 的设计思路更像是“把绑定信息放在调用结构里”编译器甚至可以把常见的get()优化成非常轻量的读取。配合虚拟线程时尤其舒服虚拟线程会被迁移、挂起、恢复ThreadLocal 在线程切换时要么丢失要么错乱ScopedValue 通过结构化传播能在虚拟线程之间正确传递。这也是为什么社区共识是未来虚拟线程应用里ScopedValue 才是“正统”的上下文传递方式ThreadLocal 只是历史遗留方案。3. ScopedValue 实操API 与三个高频用法3.1 最基础的绑定和读取where run先写一个最小可运行示例import java.util.concurrent.ScopedValue; public class ScopedValueDemo { private static final ScopedValueString TRACE_ID ScopedValue.newInstance(); private static final ScopedValueString USER_ID ScopedValue.newInstance(); public static void main(String[] args) { ScopedValue.where(TRACE_ID, trace-20240910-001) .where(USER_ID, user-10086) .run(() - { System.out.println(trace TRACE_ID.get()); System.out.println(user USER_ID.get()); nestedCall(); }); } private static void nestedCall() { // 在同一个调用链里直接读就行 System.out.println(nested trace TRACE_ID.get()); System.out.println(nested user USER_ID.get()); } }几个关键点ScopedValue.newInstance()创建一个键通常声明为static final因为它本身只用来标识不需要修改。ScopedValue.where(key, value)返回一个 Carrier可以继续.where(key2, value2)链式绑定多个值最后用.run(Runnable)或.call(Callable)执行。绑定作用域内任何嵌套方法都能通过key.get()读取。这是它很好用的点——服务层的深层次方法不用一路传参跟 ThreadLocal 的用法习惯很像。离开run作用域后再调用key.get()会抛NoSuchElementException而不是返回 null。如果你的 JDK 预览版本里有三参数便捷写法ScopedValue.where(key, value, runnable)效果是一样的看个人习惯选择。3.2 无值兜底与异常orElse / orElseThrow有些场景里某个 ScopedValue 可能没有绑定比如匿名用户你不想让它直接抛异常。ScopedValue 提供了orElse和orElseThrowString userId USER_ID.orElse(anonymous); String tenantId TENANT_ID.orElseThrow(() - new IllegalStateException(未找到租户信息));这两个方法非常实用。特别是写开源组件或者基础框架时orElseThrow能让错误从上层的where绑定处爆发出来而不是在业务代码深处抛一个“找不到变量”的隐性问题。定位错误要容易太多。需要注意ScopedValue不允许绑定 null 值。如果你写了ScopedValue.where(KEY, null)直接抛NullPointerException。这也是和 ThreadLocal 的一个明显差异——ThreadLocal 允许 set(null)然后 get 返回 null容易把“没绑定”和“绑定了 null”混为一谈。3.3 跨线程传递普通线程、虚拟线程与线程池的正确姿势先说结论ScopedValue 在“结构化执行”场景下跨线程很自然但在“非结构化线程池”场景下需要你手动做一步重新绑定。普通线程和虚拟线程只要是在绑定作用域内创建的都会自动继承当前绑定ScopedValue.where(TRACE_ID, trace-001).run(() - { // 虚拟线程创建时自动继承 TRACE_ID Thread.startVirtualThread(() - { System.out.println(TRACE_ID.get()); // trace-001 }); });这里虚拟线程拿到的不是一份“全量复制”而是一个与创建点调用结构绑定的快照成本比 InheritableThreadLocal 低得多。这也是为什么虚拟线程 ScopedValue 是个黄金组合。但线程池不同。你提交给固定线程池的任务执行现场已经脱离了绑定作用域直接 get 会抛 NoSuchElementExceptionExecutorService pool Executors.newFixedThreadPool(4); ScopedValue.where(TRACE_ID, trace-001).run(() - { String traceId TRACE_ID.get(); // 作用域内取值OK pool.submit(() - { // 这里直接 TRACE_ID.get() 会抛 NoSuchElementException // 正确做法在任务体里重新绑定 ScopedValue.where(TRACE_ID, traceId).run(() - { doHeavyWork(); }); }); });这种“提取局部变量 → 任务内重新绑定”的写法虽然多包了一层但语义非常清晰任务启动点带过去的上下文是提交那一刻的快照而不是线程池线程“自然继承”的全局状态。配合固定线程池照样不会脏数据串线。3.4 给业务代码做个小封装少写样板代码如果你经常要在线程池里传递同一批 ScopedValue可以做个工具类把绑定动作封装起来提交任务时一行搞定public final class ScopedRunnables { public static Runnable bind(Runnable task) { // 把当前线程能拿到的 ScopedValue 值收集起来 MapScopedValueObject, Object snapshot snapshot(); return () - { ScopedValue.Carrier carrier null; for (var entry : snapshot.entrySet()) { if (carrier null) { carrier ScopedValue.where(entry.getKey(), entry.getValue()); } else { carrier carrier.where(entry.getKey(), entry.getValue()); } } if (carrier null) { task.run(); } else { carrier.run(task); } }; } }说实话这个工具类写起来还是有点笨重更好的做法是直接复用线程池的“每任务一提交”封装或者进一步在提交入口用记录类统一建模。这也是为什么我建议新代码优先用虚拟线程遵循结构化并发能从根本上少很多这类包装逻辑。4. 从 ThreadLocal 迁移到 ScopedValue一个完整改造案例4.1 场景设定请求级上下文我拿一个最常见的业务场景举例Web 请求进来之后需要把 requestId、userId、tenantId 绑定到请求链路里方便业务层随时读取和写日志。旧代码基于 ThreadLocal改造目标是切到 ScopedValue同时不影响业务代码调用方式。旧代码大概是这样的public final class RequestContextHolder { private static final ThreadLocalRequestInfo CTX new ThreadLocal(); private RequestContextHolder() { } public static void set(RequestInfo info) { CTX.set(info); } public static RequestInfo get() { return CTX.get(); } public static void clear() { CTX.remove(); } }过滤器里手动管理生命周期public class RequestFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { RequestInfo info buildInfo(request); RequestContextHolder.set(info); try { chain.doFilter(request, response); } finally { RequestContextHolder.clear(); } } }业务层用的时候RequestInfo info RequestContextHolder.get(); String traceId info.traceId();这套代码在很多老项目里跑了好几年问题也积累了不少偶尔有人忘了 clear 导致上下文串线程池里跑异步任务的时候子任务拿不到父任务的值为了传递 traceId又引了 TTL代码越来越重。4.2 改造后ScopedValue 版本长什么样改造的第一步把“可写的 ThreadLocal 容器”换成“不可变的 ScopedValue 键”public final class RequestScopedContext { public static final ScopedValueRequestInfo INFO ScopedValue.newInstance(); private RequestScopedContext() { } public static RequestInfo get() { return INFO.orElseThrow(() - new IllegalStateException(当前不在请求作用域内)); } }过滤器改造public class RequestFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { RequestInfo info buildInfo(request); ScopedValue.where(RequestScopedContext.INFO, info) .run(() - { // 整个请求处理链路都在绑定作用域内 chain.doFilter(request, response); }); } }业务层读取的代码几乎不用动只是从RequestContextHolder.get()换成RequestScopedContext.get()。因为 ScopedValue 是 static final 的键业务方法里随时可读跟原来 ThreadLocal 静态工具类一样方便。改造后的最大差异是“生命周期不需要手动维护”。作用域结束绑定自然消失。不会再有“过滤器里忘 clear”这种低级错误代码 review 起来也轻松很多。4.3 异步任务迁移线程池和虚拟线程分别怎么处理原来的异步链路是最折腾人的。线程池任务拿不到 ThreadLocal要么引入 TTL要么手动把 RequestInfo 作为参数一路传下去。改造成 ScopedValue 之后分两种情况处理。如果线上用的是虚拟线程或者准备上虚拟线程可以直接利用结构化继承ScopedValue.where(RequestScopedContext.INFO, info).run(() - { // 在作用域内创建虚拟线程自动继承上下文 Thread.startVirtualThread(() - { asyncService.doWork(); }); });如果你还离不开固定线程池就得在任务执行体里重新绑定一次。注意取快照的动作必须发生在提交任务的绑定作用域内ScopedValue.where(RequestScopedContext.INFO, info).run(() - { RequestInfo snapshot RequestScopedContext.get(); executor.submit(() - { ScopedValue.where(RequestScopedContext.INFO, snapshot).run(() - { asyncService.doWork(); }); }); });这样改完业务代码本身没有过多侵入但异步传值的语义变得非常明确线程池任务拿到的是提交时刻的上下文快照而不是某个“神秘线程”上残留的可变状态。4.4 迁移清单哪些能迁哪些要缓一缓不是所有 ThreadLocal 都适合迁到 ScopedValue。我自己总结了一个判断清单值只在请求链路/任务链路生命周期内有效且基本不会被修改适合迁移。典型traceId、userId、tenantId、请求快照。值需要在线程运行期间频繁改写慎迁。典型统计计数、动态开关、变更中的配置。依赖 Spring、Netty、日志框架等底层 ThreadLocal 的生态先别动。第三方库内部是 ThreadLocal外部你用 ScopedValue 也影响不到它。JDK 版本在 21 以下的迁移成本会比较高建议等基础设施升级后再考虑。迁移节奏上我建议先做“双轨跑通”新代码用 ScopedValue老代码继续 ThreadLocal中间加一层适配保证业务方不用感知底层变化。跑一两个版本、压测稳定后再逐步切核心链路。5. 常见问题与避坑指南5.1 常见问题速查表问题原因 / 表现解决办法作用域外调 get() 抛异常ScopedValue 未绑定语义是“当前不在作用域内”用 orElse 给兜底值或用 orElseThrow 转换成更明确的业务异常绑定时值传 null 直接 NPEScopedValue 不允许 null 绑定绑定前判空或把兜底值放在业务代码里处理线程池任务里拿不到值任务脱离了绑定作用域在提交处取快照任务内重新绑定或改用虚拟线程子线程改了值父线程看不到不可变设计改动必须重新绑定理解“新值新作用域”的模型不要试图在作用域内二次赋值JDK 版本不支持需要 JDK 21且旧版本要开 preview 编译确认 JDK 版本预览阶段开启 --enable-preview转正后无需与 TTL 混用时值不一致两套传递机制不互通明确边界同一份上下文只走一套机制避免双写5.2 几个容易踩的坑第一把可变对象塞进 ScopedValue。虽然 ScopedValue 的绑定本身不可变但如果你绑进去一个Map、List或者有 setter 的 POJO子线程照样能改这个对象的内部状态等于把不可变设计架空了。正确做法是绑“值对象”优先用 record 建模真正做到只读快照。第二在任何地方无脑包ScopedValue.where(...)。ScopedValue 虽然精巧但它本质上是一种作用域内的绑定结构不该出现在一个每秒执行上万次的循环内部去重复创建。把绑定提升到请求链路入口而不是让每个方法都自作主张地创建新作用域。第三测试场景里忘了绑定。写单元测试时直接调RequestScopedContext.get()会因为不在绑定作用域内而抛异常。要么在测试里包一层ScopedValue.where(...).run(...)要么给业务代码提供orElse兜底避免测试代码被强制绑定搞得很别扭。第四预览版本与正式版本混用。JDK 21 到 JDK 24 期间ScopedValue 属于孵化或预览特性有的版本需要加--enable-preview有的不需要不同版本的包路径也可能有差异。生产环境建议等转正之后的 JDK 版本至少保证开发、测试、生产三套环境的 JDK 版本完全一致。5.3 什么时候千万别硬上 ScopedValueScopedValue 不是万能钥匙。如果你遇到下面这几种情况老老实实用回 ThreadLocal 反而更稳场景要求“同线程内反复修改上下文”比如记录当前累计值、计数器之类。ScopedValue 不可变改一次就要开一个新作用域反而别扭。项目 JDK 版本低于 21升级 JDK 本身成本巨大就别为了这个特性搞大版本跳跃。整个系统重度依赖 ThreadLocal 的第三方框架你切了 ScopedValue 也无法改变第三方内部的传递逻辑最后变成两套上下文体系并存更乱。上下文是“绕过作用域的”比如一个任务被扔到线程池执行时机完全脱离提交结构。这里是 ScopedValue 的弱项传统 ThreadLocal 手动快照或者 TTL 反而更灵活。技术选型这件事讲究的是“正好合适”不是“新的更好”。ScopedValue 在结构化场景下非常香但如果你业务全是非结构化异步任务硬上只会给自己找麻烦。5.4 生态现状与下一步建议到目前为止Spring、Netty、日志框架等主流生态的内部上下文管理仍然大量基于 ThreadLocal。这不是它们不认可 ScopedValue而是兼容性、迁移成本和历史包袱的问题。对业务开发者来说短期内不可能完全抛弃 ThreadLocal但新项目的架构选型已经开始往 ScopedValue 倾斜了。我建议的打法是新开的服务、新写的中间件、新设计的请求上下文优先用 ScopedValue老系统则先选一条非核心链路试点跑顺了再推广。同时把虚拟线程、结构化并发这些兄弟特性放在一起评估因为它们组合起来才能发挥最大价值。个人实际操作中还有一个体会ScopedValue 最大的收益其实不是“快”而是“稳”。线程池脏数据、漏 remove 导致的内存泄漏、InheritableThreadLocal 复制开销这些在 ThreadLocal 时代需要靠规范和纪律去控制的东西换到 ScopedValue 之后从机制上就没了。代码评审的时候少花一半时间检查上下文的 set/remove这种心情愉悦感比那百分之几的性能提升实在多了。