Java虚拟线程与ThreadLocal状态隔离的使用边界

Java 虚拟线程可以使用 ThreadLocal，但“能用”不等于“适合放任何东西”。正确边界是：把短生命周期、任务私有的请求上下文放进去；不要把连接、客户端、大缓存和其他可复用资源绑定到每个虚拟线程。这样既保留状态隔离，又避免虚拟线程数量放大内存与资源占用。

官方地址：https://docs.oracle.com/en/java/javase/26/core/virtual-threads.html

ThreadLocal 隔离的是虚拟线程，不是 carrier 线程

虚拟线程会在不同的 carrier 上运行，代码能看到的 Thread.currentThread() 仍是虚拟线程本身。因此，carrier 上设置的 ThreadLocal 不会自动出现在虚拟线程里，虚拟线程的值也不会因为换了 carrier 而混到其他任务中。这个性质适合保存一次请求内的 traceId、租户标识或小型解析上下文。

请求级状态要有明确的设置与清理边界

下面的写法把状态限制在一次任务内。示例中的上下文只保存轻量字符串；真正的业务对象应尽量改成方法参数，避免隐式依赖扩散。

// 请求级上下文只保存轻量、不可变的标识，避免把资源塞进 ThreadLocal
static final ThreadLocal REQUEST_CONTEXT = new ThreadLocal();

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    executor.submit(() -> {
        // 每个虚拟线程只处理一个任务，状态不会与其他任务共享
        REQUEST_CONTEXT.set(new RequestContext("trace-7f2a", "tenant-a"));
        try {
            handleRequest();
        } finally {
            // 即使任务抛错也清除引用，缩短上下文的可达时间
            REQUEST_CONTEXT.remove();
        }
    });
}

remove() 不是为了修复虚拟线程与 carrier 的串值问题，而是为了让状态尽快失去引用，特别是在任务对象、异常对象或线程仍被诊断工具保留时。更稳妥的做法是让 handleRequest 接收显式参数；ThreadLocal 只承担跨层传递确实难以改造的少量上下文。

大对象和可复用资源不应绑定到每个虚拟线程

平台线程池时代常见的做法是用 ThreadLocal 缓存格式化器、缓冲区或连接。虚拟线程的设计目标是按任务创建，数量可以远大于平台线程；同一 JVM 里如果同时存在大量虚拟线程，每个线程都持有一个大对象，内存峰值会直接被放大。

继承状态和只读上下文需要单独判断

InheritableThreadLocal 的值是在创建子线程时取得初始值；如果值本身是可变对象，父子线程可能仍指向同一个对象，所谓“继承”并不等于深拷贝。虚拟线程数量较多时，批量复制复杂上下文也会增加分配和排查成本。只读、有明确作用域的上下文可以评估 ScopedValue；需要修改、清理或生命周期复杂的对象，优先采用显式参数或专门的上下文对象。

迁移前的检查清单

先搜索所有 ThreadLocal 和 InheritableThreadLocal，逐项回答三个问题：值是否小于一次任务的生命周期、是否包含连接或大缓冲区、是否能改成显式参数。如果仍需定位遗留设置，可以在诊断环境使用：

# 仅在诊断环境打开虚拟线程 ThreadLocal 设置堆栈，便于定位遗留代码
java -Djdk.traceVirtualThreadLocals=true -jar app.jar

这个属性用于发现设置动作，不应直接当成生产常驻开关。迁移完成后，再检查任务异常路径是否执行 remove()，资源是否由池或应用级组件统一关闭。

常见问题

虚拟线程会共享 carrier 的 ThreadLocal 吗？

不会。Java 代码看到的是虚拟线程，carrier 的 ThreadLocal 对虚拟线程不可见。

ThreadLocal 在虚拟线程里是不是完全不能用？

不是。小型请求上下文仍可使用，但要控制对象大小、生命周期和清理路径。

为什么不能用 ThreadLocal 缓存数据库连接？

虚拟线程数量可能很大，而且每个虚拟线程只服务一个任务；连接应交给连接池显式借还。

什么时候应该改成 ScopedValue？

当数据主要是只读、需要沿调用链传递并具有明确作用域时，可以评估 ScopedValue；它不能替代需要修改或关闭的资源。

判断标准可以压缩成一句话：ThreadLocal 保存的是“这次任务的轻量上下文”，不是“为了复用而缓存的资源”。