JDK 25 ScopedValue 实战:替换 ThreadLocal 后我踩过的六个坑

2026-11-17 0 708

事情是这样的。我们后端有个链路追踪的小工具,用 ThreadLocal 存 traceId,每个请求进来在过滤器里 set 一下,业务层随手 get 出来打日志。写了五六年,一直挺稳。

前阵子把一部分 IO 密集的任务切到虚拟线程上,出问题了。压测时机器内存曲线一路上扬,GC 也压不下去。抓了堆快照一看,几十万个 ThreadLocalMap 挂在虚拟线程上——虚拟线程虽然便宜,但每个线程一个 ThreadLocalMap 也不便宜。另一个问题是线程池复用:提交任务前忘记清、或者异常路径漏了 finally 的 remove,下一个任务进来就拿到了上个任务的 traceId,日志里张冠李戴。

JDK 25 里 ScopedValue 从预览转为正式,正好拿来替换。下面是我改完之后整理的实操记录,代码都在 JDK 25 上跑过。

先看清楚 ScopedValue 长什么样

它跟 ThreadLocal 的 API 完全不一样。ThreadLocal 是”先拿个容器,再往里塞”;ScopedValue 是”一个不可变的 key,绑定一次,作用域结束自动失效”。

public class FirstLook {
    private static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();

    public static void main(String[] args) {
        ScopedValue.where(TRACE_ID, "trace-001").run(() -> {
            System.out.println(TRACE_ID.get());     // trace-001
        });

        System.out.println(TRACE_ID.isBound());     // false
    }
}

关键点三个:ScopedValue.newInstance() 创建一个 key,这个 key 是 final 的常量,全局共用;ScopedValue.where(key, value) 返回一个 Carrier;carrier.run() 或者 carrier.call() 执行的时候,绑定才生效,方法返回或者抛异常,绑定就自动解除。

没有 set(),没有 remove()。这两个方法在 ThreadLocal 时代是事故重灾区,现在直接消失了。

案例:改造我们的链路追踪上下文

先说结论:我把 TraceContext 这个工具类重写了。原来它长这样:

public class TraceContext {
    private static final ThreadLocal<String> TRACE = new ThreadLocal<>();

    public static void set(String traceId) { TRACE.set(traceId); }
    public static String get() { return TRACE.get(); }
    public static void clear() { TRACE.remove(); }
}

调用方需要在 try-finally 里 set 和 clear,漏一个就出事。新版是这样:

public final class TraceContext {
    private static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();

    private TraceContext() {}

    public static ScopedValue.Carrier withTrace(String traceId) {
        return ScopedValue.where(TRACE_ID, traceId);
    }

    public static String currentTraceId() {
        return TRACE_ID.isBound() ? TRACE_ID.get() : "-";
    }

    public static ScopedValue<String> key() {
        return TRACE_ID;
    }
}

注意 currentTraceId() 那里用了 isBound() 做兜底。ScopedValue 在未绑定时调 get() 会抛 NoSuchElementException,跟 ThreadLocal 返回 null 的行为不一样。日志打印这种场景我宁可返回一个占位符,不要让日志代码自己炸掉把业务带崩。

也可以用 TRACE_ID.orElse("-"),效果一样,写起来更短。

在拦截器里包住整个请求

之前用 ThreadLocal 的写法是 preHandle 里 set,afterCompletion 里 clear。换成 ScopedValue 之后,整个请求的处理必须包在 carrier.call() 里面,Spring MVC 的拦截器做不到这一点——preHandle 返回之后,作用域已经结束了。

所以我把入口挪到了 Filter 上:

@Component
public class TraceFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) req;
        String traceId = request.getHeader("X-Trace-Id");
        if (traceId == null || traceId.isBlank()) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }

        try {
            TraceContext.withTrace(traceId).run(() -> {
                try {
                    chain.doFilter(req, resp);
                } catch (IOException | ServletException e) {
                    throw new UncheckedIOException(new IOException(e));
                }
            });
        } catch (UncheckedIOException e) {
            throw e.getCause();
        }
    }
}

这里被 lambda 逼着处理了一下检查异常。Carrier.run() 接的是 Runnable,里面不能抛受检异常。chain.doFilter 声明了 IOException 和 ServletException,所以我包了一层 UncheckedIOException,外面再拆开。如果嫌丑,可以自己写个函数式接口 + @FunctionalInterface,方法签名带 throws Exception,内部用 carrier.call() 走。这只是包装方式的问题,不影响 ScopedValue 本身。

这种”整个请求全程在作用域里”的结构有个额外的好处:你在任何一层代码里,只要还在处理这个请求,就一定能读到 traceId。不用传参,不用往 Request 属性里塞,业务代码彻底解耦。

跨线程才是重点

ScopedValue 跟 ThreadLocal 最大的区别之一,就是它不会自动传给子线程。这在虚拟线程时代反而是优点——ThreadLocal 的所有继承变体(InheritableThreadLocal、线程池的 TransmittableThreadLocal)都会拖慢虚拟线程的创建,还有内存泄漏风险。

但不传不代表不能传,只是要显式地传。做法是把 Carrier 当成参数传进去:

public class AsyncDemo {
    public static void main(String[] args) throws Exception {
        var carrier = TraceContext.withTrace("trace-abc");

        carrier.run(() -> {
            Thread.ofVirtual().start(() -> {
                System.out.println("子线程读到: " + TraceContext.currentTraceId());
                // 输出: 子线程读到: -

                // 显式进入作用域
                carrier.run(() -> {
                    System.out.println("重新进入: " + TraceContext.currentTraceId());
                    // 输出: 重新进入: trace-abc
                });
            });
        });
    }
}

Carrier 是可以在多个线程里重复执行的,因为它只记录了”key 到 value 的映射”,本身没有可变状态。你在哪个线程上执行 carrier.run(),那个线程就进入这个作用域,方法结束就退出。这个设计比 ThreadLocal 干净太多——ThreadLocal 的”继承”是一个持续的状态,ScopedValue 的”传递”是一次性的动作。

线程池里怎么传

真实项目里大部分异步任务都是提交给 ThreadPoolExecutor 或者 Spring 的 @Async。这时候有两个选择。

方案 A:提交时把 Carrier 一起传

public class TraceAwareTask implements Runnable {
    private final ScopedValue.Carrier carrier;
    private final Runnable body;

    public TraceAwareTask(ScopedValue.Carrier carrier, Runnable body) {
        this.carrier = carrier;
        this.body = body;
    }

    @Override
    public void run() {
        carrier.run(body);
    }
}

// 使用
var carrier = TraceContext.withTrace(traceId);
executor.submit(new TraceAwareTask(carrier, () -> doSomething()));

方案 B:用 StructuredTaskScope(JDK 25 里仍是预览特性,需要 --enable-preview)

Structured Concurrency 在 JDK 25 里是第五次预览(JEP 505),它对 ScopedValue 的支持是”fork 出的子任务自动继承父任务的作用域绑定”,不需要你手动包装:

try (var scope = StructuredTaskScope.<String>open()) {
    var subtask = scope.fork(() -> {
        // 这里直接能读到父线程绑定的 traceId
        return TraceContext.currentTraceId();
    });
    scope.join();
    System.out.println(subtask.get());
}

注意这个写法需要 --enable-preview,并且要在编译时和运行时都加上这个参数。如果你们的项目还没上预览特性,老老实实用方案 A。

顺带说一句,Executors.newVirtualThreadPerTaskExecutor() 和 StructuredTaskScope 在语义上是不一样的。前者的每个任务是一个独立的虚拟线程,ScopedValue 不会自动带过去;后者是父子任务结构,继承是规范的一部分。这个区别我在迁移时被坑过一次,以为换了个线程就自动带过去了,结果日志里 traceId 全是 -。

六个坑,按踩到的顺序

坑一:以为子线程会继承

刚改完那两天,日志里异步任务的 traceId 一片空白。我还以为是 currentTraceId() 的兜底写错了,查了半天才发现虚拟线程根本不继承作用域值。后来统一改成”提交任务时显式带 Carrier”,日志才正常。这个问题在文档里写得挺清楚,只是我上手时凭 ThreadLocal 的经验想当然了。

坑二:作用域外 get 会抛异常

ThreadLocal 未设置时返回 null,写代码的时候习惯了 if (TraceContext.get() != null)。换成 ScopedValue 之后 get() 直接抛 NoSuchElementException,一堆日志代码和调试输出全挂了。新版工具类里我加了 isBound() 的兜底,把抛异常的行为收在工具类内部。

坑三:不能 set,只能重新开作用域

业务里有一段逻辑,会根据 sub-request 生成一个子 traceId,需要”在原有上下文上覆盖”。ThreadLocal 时代直接 set(newTraceId) 就行,ScopedValue 不行。我改成在子逻辑里再开一层:

ScopedValue.where(TRACE_ID, subTraceId).run(() -> {
    // 这里读到的是 subTraceId
});
// 出了作用域,自动恢复为外层的 traceId

这其实比 ThreadLocal 的”覆盖再恢复”安全,不用写 try-finally,也不怕异常。代价是”覆盖”不再是原地修改,原来那种”某个方法里改一下,后面所有调用都能读到”的写法得重构掉。

坑四:同一个 key 重复绑定,是遮蔽不是合并

嵌套作用域的时候,内层绑定同一个 key 会遮蔽外层,作用域结束后外层恢复,这个行为是正确的。但如果业务代码以为内外两层的值会合并,就会踩坑。举个反例:外层绑了一个对象 UserContext,内层想”只改其中某个字段”,结果写了一个新对象塞进去,外层那个对象根本没被动过。改起来必须把新对象整体拷一遍再 where 进去,不能指望”改一部分”。

坑五:别把大对象塞进去

每次 ScopedValue.where() 都会创建一个新的 Carrier 对象,这个对象里存的是 key-value 数组。如果 value 是一个几十 MB 的对象,每次方法调用都 where 一下,堆里很快就堆满短命的 Carriers。ScopedValue 适合放小对象——ID、名称、上下文元数据。大对象老老实实当参数传。

坑六:跟 MDC、Spring 的 RequestContextHolder 混着用要小心

日志框架的 MDC 底层是 ThreadLocal,跟 ScopedValue 是两套机制。我们的日志格式里要输出 traceId,原来靠 MDC 的 %X{traceId},现在得在 Filter 里手动往 MDC 里放一份,退出作用域前清掉。同理,Spring 的 RequestContextHolder 也是 ThreadLocal,ScopedValue 没法替代它。

更麻烦的是执行顺序。MDC 的设置必须跟 ScopedValue 的作用域重叠,但两者的生命周期又不完全一致。我最后的做法是:在 ScopedValue 的作用域内部再套一层 MDC 的 put/remove,用 try-finally 保证配对。日志这块还是得跟 ThreadLocal 打交道,只是范围收得很小,只在这儿。

值得说清楚的取舍

换了之后我最大的感受是:ScopedValue 不是”更好的 ThreadLocal”,它是”另一个东西”。

ThreadLocal 本质是”线程自己的一个变量”,你可以 set、可以 get、可以 clear,自由度很高,也容易漏。ScopedValue 本质是”一个作用域内的只读常量”,你只能在进入作用域的时候定死,作用域结束就没了,自由度低很多,但也就不容易出错。

如果你们项目里 ThreadLocal 是用来存”请求上下文”(用户身份、traceId、租户 ID),这些值在请求生命周期内是不变的,ScopedValue 是天然适配。如果 ThreadLocal 是被业务代码当”临时缓存”用——set 之后在好几个方法里反复改——那迁移过去会非常痛苦,不如先不动。

还有一点:虚拟线程不是 ScopedValue 的前置条件。你用平台线程也能直接用 ScopedValue,只是省下的资源和修复的问题没那么明显。虚拟线程之所以推 ScopedValue,是因为在千万级虚拟线程的场景下,ThreadLocal 的内存开销和生命周期管理终于变成了真问题。

完整可跑的最小版本

把上面东西拼起来,这是一个不依赖框架、直接 java 命令就能跑的例子:

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class ScopedValueDemo {

    static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();
    static final ScopedValue<String> TENANT = ScopedValue.newInstance();

    public static void main(String[] args) throws Exception {
        var carrier = ScopedValue.where(TRACE_ID, "trace-9f2c")
                                 .where(TENANT, "tenant-1001");

        ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor();

        carrier.run(() -> {
            System.out.println("[main] " + TRACE_ID.get() + " / " + TENANT.get());

            pool.submit(() -> {
                System.out.println("[pool 无包装] " + TRACE_ID.orElse("未绑定"));

                carrier.run(() -> {
                    System.out.println("[pool 有包装] " + TRACE_ID.get() + " / " + TENANT.get());
                });
            }).get();
        });

        pool.shutdown();
        System.out.println("[结束后] " + TRACE_ID.isBound());
    }
}

输出大致如下:

[main] trace-9f2c / tenant-1001
[pool 无包装] 未绑定
[pool 有包装] trace-9f2c / tenant-1001
[结束后] false

把 orElse 换成 get(),第二行那里会直接抛 NoSuchElementException。这个差别值得自己动手跑一遍,比看十篇文档都有印象。

如果你现在的项目还在 JDK 17 或者 21 上,ScopedValue 用不上,但这套思路可以先拿过来:把 ThreadLocal 的 set/clear 收进一个 try-finally 的封装里,别散落在业务代码各处。等后面升到 25 的时候,替换起来就是机械劳动,不用重新设计。

JDK 25 ScopedValue 实战:替换 ThreadLocal 后我踩过的六个坑
收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
点赞 (0)

版权声明:
本站资源有的来自互联网收集整理,本站纯免费分享提供学习使用,如果侵犯了您的合法权益,请发送邮件1506151422@qq.com联系,将会及时下架删除。
本站资源仅供研究、学习交流之用,免费开源项目不代表完全可商用,若商业用途请先咨询开发企业能否商用,否则产生的一切后果将由下载用户自行承担。
原创板块未经允许不得转载,否则将追究法律责任。

淘吗网 java JDK 25 ScopedValue 实战:替换 ThreadLocal 后我踩过的六个坑 https://www.taomawang.com/server/java/3024.html

下一篇:

已经没有下一篇了!

常见问题

相关文章

猜你喜欢
发表评论
暂无评论
官方客服团队

为您解决烦忧 - 24小时在线 专业服务