Java 虚拟线程怎样为 ThreadLocal 上下文设置继承边界

虚拟线程可以使用 ThreadLocal，但这不代表请求上下文会自动以你期望的方式传播。最稳妥的做法是先区分三件事：普通 ThreadLocal 只属于当前线程；InheritableThreadLocal 在创建子线程时复制初始值；Java 25 的 ScopedValue 则把只读数据绑定到一段明确的动态作用域。任务边界一旦确定，虚拟线程就不应继续依赖“创建它的线程当时有什么值”。

先拆开三种上下文载体

ThreadLocal 解决的是“同一个线程里的代码共享一份私有值”，它不会把普通值传给新建线程。虚拟线程换到哪个载体平台线程执行，也不改变 Thread.currentThread() 返回的逻辑线程，因此不能把载体线程当作上下文容器。

InheritableThreadLocal 的复制发生在子线程创建时，复制的是初始值，不是后续同步。如果值是可变的 Map、Session 或连接包装器，父子任务还可能意外共享对象。Java 25 API 文档也明确提供了关闭这类初始继承的构建器选项。

用 Thread.Builder 切断不需要的继承

迁移旧代码时，先把虚拟线程工厂配置成“默认不继承”。这样做的意义不是让所有上下文都消失，而是让每一种需要传播的值都必须经过显式设计。下面的示例保留一个兼容旧库的可继承变量，同时让新建任务明确选择隔离：

import java.util.concurrent.ThreadFactory;

public final class VirtualThreadBoundary {
    private static final InheritableThreadLocal TRACE =
            new InheritableThreadLocal();

    public static ThreadFactory isolatedFactory() {
        // false 表示新虚拟线程不复制创建线程的初始继承值
        return Thread.ofVirtual()
                .name("job-", 0)
                .inheritInheritableThreadLocals(false)
                .factory();
    }

    public static void submitOne() {
        TRACE.set("parent-trace");
        Thread task = isolatedFactory().newThread(() -> {
            // 隔离后这里不会自动看到 parent-trace；需要显式传参或重新绑定
            String value = TRACE.get();
            System.out.println("child trace = " + value);
        });
        task.start();
    }
}

需要注意的是，inheritInheritableThreadLocals(false) 只影响线程创建时的初始继承；它不会替你清理普通 ThreadLocal，也不会把任务参数自动传过去。对于必须传播的追踪 ID，直接把不可变值作为任务参数传入，通常比扩大可继承状态更容易审计。

用 ScopedValue 固定上下文生命周期

如果上下文只需要“由调用方向下游只读传递”，Java 25 的 ScopedValue 更贴合这个模型。where(...).run(...) 建立绑定，嵌套作用域可以临时重绑定，回调返回后自动恢复原值；远处方法只能读取拥有 key 的值，不会像 ThreadLocal 一样在任意位置留下新状态。

import java.lang.ScopedValue;

public final class RequestContext {
    private static final ScopedValue REQUEST_ID =
            ScopedValue.newInstance();

    static void handle(String requestId) {
        // 绑定只覆盖 run 的动态作用域，结束后 REQUEST_ID 自动解除
        ScopedValue.where(REQUEST_ID, requestId).run(() -> {
            logStart();
            doBusinessWork();
        });
    }

    private static void logStart() {
        // 读取未绑定值会抛异常，orElse 可用于可选上下文
        System.out.println("request = " + REQUEST_ID.orElse("missing"));
    }

    private static void doBusinessWork() {
        // 这里可以跨多层调用读取，但不能修改 REQUEST_ID 的绑定
        System.out.println("work for " + REQUEST_ID.get());
    }
}

在结构化并发场景中，StructuredTaskScope 创建的子任务可以继承创建作用域捕获的 ScopedValue 绑定；共享对象本身仍应保持不可变，或自行同步。不要把一个可变的请求上下文 Map 塞进 ScopedValue 后再让多个子任务同时修改，那只是把泄漏从线程局部换成了数据竞争。

迁移时用指标确认边界真的生效

不要只看任务能否跑完。先做一组基线，再比较关闭继承、改用显式参数或 ScopedValue 后的结果。重点记录虚拟线程数量、每个任务的上下文命中率、未绑定读取异常、请求结束后的对象存活，以及高并发下的堆占用。

最后一条很容易被忽略：虚拟线程便宜，但数据库连接、文件句柄和外部服务并不会因此变便宜。JEP 444 明确建议不要把虚拟线程当作需要池化的资源；如果要限制下游并发，应使用信号量等资源控制手段，而不是把虚拟线程放进小线程池。

常见问题

虚拟线程会继承载体平台线程的 ThreadLocal 吗？

不会。虚拟线程拥有自己的线程局部变量视图，载体平台线程的 ThreadLocal 对虚拟线程不可见；需要关注的是显式使用的 InheritableThreadLocal。

关闭继承后，旧框架读取不到用户信息怎么办？

先确认它读取的是 InheritableThreadLocal 还是普通 ThreadLocal，再通过任务参数、框架提供的上下文传播接口或 ScopedValue 显式传递。不要为了兼容而全局重新打开继承。

ThreadLocal 什么时候仍然合理？

线程状态确实属于当前执行线程、生命周期短且可以在 finally 中清理时仍可使用。只读调用链上下文则更适合 ScopedValue；昂贵资源不要用 ThreadLocal 伪装成资源池。