Java virtual threads 与 ThreadLocal 资源绑定的清理边界

把线程池任务改成 Java virtual threads 后，ThreadLocal 仍然可以使用，但它的职责边界必须重新看清：请求 ID、租户标识这类上下文可以绑定；数据库连接、输入流、临时文件句柄和昂贵的可变对象不应该把 ThreadLocal 当成清理器。最稳妥的规则是：资源由 try-with-resources 管理，ThreadLocal 只承载确实需要按线程访问的状态。

virtual thread 结束、ThreadLocal.remove() 和资源 close() 是三个不同动作。remove() 只清除当前线程的绑定，不会自动调用资源的 close()；因此外部资源必须在任务作用域内显式关闭。

一次迁移故障是怎样出现的

原来的服务使用固定大小的平台线程池，每个任务从 ThreadLocal 取出上下文和临时对象。迁移到 Executors.newVirtualThreadPerTaskExecutor() 后，请求量一上来，问题通常表现为三个信号：ThreadLocal 中的对象创建次数明显增加；连接、流或临时文件的占用释放不及时；偶发异常路径比正常路径更容易留下未关闭资源。

根因不是“虚拟线程不能使用 ThreadLocal”。Oracle 的虚拟线程指南明确说明，虚拟线程支持线程本地变量，但单个 JVM 可能承载大量虚拟线程，所以不应把昂贵的可复用对象继续当作 ThreadLocal 缓存。虚拟线程也不是载体线程的别名，代码中的 Thread.currentThread() 取得的是正在执行任务的虚拟线程。

先区分三个生命周期边界

迁移时可以把一次任务画成三个同心边界，但不要把它们合并成一个“线程结束就会清理”的概念。

• 任务边界：虚拟线程从启动到任务结束。它适合承载一次请求或一个独立工作单元。
• 绑定边界：ThreadLocal 在当前线程上保存的值。调用 remove() 后，当前线程再次 get() 时可能重新执行初始化。
• 资源边界：连接、文件、流、锁或本地句柄从获取到释放。它必须由资源协议决定，通常是 close()、release() 或显式回滚。

虚拟线程通常不会像固定平台线程那样被无关任务反复复用，所以 ThreadLocal 的“跨请求串值”风险形态会变化；但这不等于资源可以延迟关闭。一个长时间运行的虚拟线程、一个提前返回的分支，或者一个资源创建后抛出的异常，都可能让外部资源在很长一段时间内保持占用。

请求上下文可以绑定，资源句柄不要顺手绑定

适合 ThreadLocal 的通常是小而短的上下文，例如请求 ID、租户 ID 或日志关联信息。它们的价值是让深层调用无需层层增加参数，但仍然应该在一次任务结束前清除，避免把生命周期扩散到调用方看不见的地方。

private static final ThreadLocal REQUEST_ID = new ThreadLocal();

static void runWithRequestId(String requestId, Runnable action) {
    // 绑定只服务于当前任务的轻量上下文。
    REQUEST_ID.set(requestId);
    try {
        action.run();
    } finally {
        // 清除绑定，避免后续代码继续读到过期上下文。
        REQUEST_ID.remove();
    }
}

void submit(String requestId, Runnable action) {
    // 每个任务拥有自己的虚拟线程，不把连接或流塞进 ThreadLocal。
    Thread.ofVirtual().start(() -> runWithRequestId(requestId, action));
}

相反，Connection、InputStream、ZipFile、临时目录句柄和可变的非线程安全格式化器，都应该先问一句：“它的关闭动作在哪里？”如果答案只是“线程结束后应该会回收”，那就说明资源边界没有被写进代码。

把资源释放放进虚拟线程任务的作用域

一次任务只需要一个资源时，直接在虚拟线程的任务体内使用 try-with-resources。这样正常返回、业务异常和中途取消都会沿着 Java 的资源关闭规则处理，代码也不依赖 ThreadLocal 的隐式状态。

static void handleRequest(String requestId) {
    // 请求 ID 是上下文，资源本身仍由局部作用域管理。
    runWithRequestId(requestId, () -> {
        try (DemoResource resource = DemoResource.open()) {
            // 在资源有效期间完成本次任务的读写。
            process(resource, REQUEST_ID.get());
        } catch (Exception ex) {
            // 记录异常后交给上层处理，close 仍会先执行。
            logFailure(requestId, ex);
        }
    });
}

static final class DemoResource implements AutoCloseable {
    static DemoResource open() {
        // 示例只表达资源获取协议，不代表真实连接实现。
        return new DemoResource();
    }

    @Override
    public void close() {
        // 这里释放连接、文件或其他外部句柄。
    }
}

static void process(DemoResource resource, String requestId) {
    // 使用资源完成业务操作；不要把 resource 写入 ThreadLocal。
}

这里有一个容易忽略的顺序：如果上下文清理和资源关闭都需要执行，资源应先在其自身作用域内关闭，ThreadLocal 再在更外层的 finally 中移除。不要把“从 ThreadLocal 取出来”误认为“资源已经释放”。

不得不绑定资源时，必须同时 close 和 remove

少数遗留 API 只能从当前线程读取资源，这时可以把 ThreadLocal 当作访问入口，但要给它包一层明确的清理协议。关键是把 close() 与 remove() 写在同一个 finally 里，并处理关闭动作本身抛出的异常。

private static final ThreadLocal CURRENT = new ThreadLocal();

static void runWithBoundResource(Runnable action) {
    DemoResource resource = DemoResource.open();
    CURRENT.set(resource);
    try {
        // 兼容只能通过 ThreadLocal 读取资源的旧调用链。
        action.run();
    } finally {
        try {
            // remove() 不会关闭资源，所以先调用资源自己的关闭协议。
            resource.close();
        } finally {
            // 无论 close 是否抛错，都要清除当前线程的绑定。
            CURRENT.remove();
        }
    }
}

如果资源实现的关闭方法可能抛出异常，还要决定业务异常与关闭异常的主次关系。使用标准的 try-with-resources 可以自动保留抑制异常；手写 ThreadLocal 兼容层时，至少要让 remove() 位于关闭动作的内层保护之后，避免清理异常让绑定永久留在当前线程。

不要把昂贵对象误当成 virtual thread 的缓存

固定平台线程池中的 ThreadLocal 缓存有时能减少对象创建：池里只有少量线程，多个任务会复用同一份线程本地对象。虚拟线程通常是一任务一线程，跨无关任务复用的前提不再成立。把可变、非线程安全、创建成本高的对象放入 ThreadLocal，可能变成“每个任务一份”，峰值内存和初始化成本都会上升。

优先级可以这样排：

1. 对象不可变且线程安全时，使用一个共享实例，例如合适的日期格式化器。
2. 对象只服务当前调用时，直接使用局部变量或方法参数。
3. 对象确实需要隔离且有关闭协议时，把作用域写成 try-with-resources，不要把清理责任藏进 ThreadLocal。
4. 只有遗留调用链无法改造时，才使用“close 后 remove”的适配层。

只读上下文可以考虑 ScopedValue

如果需求只是把不可变的请求信息沿调用链向下传递，而不是允许深层代码随意改写状态，可以考虑 Java 26 API 中的 ScopedValue。它把值绑定在一个明确的动态作用域内，作用域结束后绑定自动恢复；这比让 ThreadLocal 拥有无界的生存期更贴合只读上下文。

private static final ScopedValue REQUEST_ID = ScopedValue.newInstance();

static void start(String requestId) {
    // 绑定只覆盖 run 的动态作用域，结束后自动恢复为未绑定状态。
    ScopedValue.where(REQUEST_ID, requestId).run(() -> deepCall());
}

static void deepCall() {
    // 只读访问请求上下文，不把数据库连接等资源放入 ScopedValue。
    String requestId = REQUEST_ID.get();
    logRequest(requestId);
}

ScopedValue 适合传递上下文，不会替你关闭连接、流或文件。它解决的是“值的可见范围和恢复”，资源仍然必须遵守自己的获取与释放协议。

迁移后按四个问题复查

排查时可以先定位所有 ThreadLocal.set、get 和 remove，再逐个追踪其中对象是否实现 AutoCloseable，以及关闭动作是否覆盖异常路径。这个静态检查通常比盯着载体线程数量更直接，因为 virtual thread 的核心问题是任务和资源的作用域是否一致。

结论

Java virtual threads 并没有取消 ThreadLocal 的适用场景，只是让“按线程缓存昂贵对象”的旧假设更容易失效。把 ThreadLocal 限定为上下文入口，把资源释放写进任务作用域；如果遗留代码确实要求绑定资源，就在同一个清理边界里先 close()，再 remove()。记住这三个动作互不替代，迁移后的资源占用和异常路径才有明确的归属。

相关问题

virtual thread 结束后 ThreadLocal 会不会一直泄漏？

线程结束后，它保存的线程本地值通常具备被垃圾回收的条件，但这不是及时关闭外部资源的保证。只要任务仍在运行，或资源本身需要显式释放，仍应在任务作用域内清理。

ThreadLocal.remove() 会调用资源的 close() 吗？

不会。remove() 只移除当前线程对该 ThreadLocal 的值；资源是否关闭取决于它自己的 API，必须显式调用 close() 或使用 try-with-resources。

虚拟线程里还能不能使用 ThreadLocal 传递请求 ID？

可以，但要限制值的大小和生存期，并在任务边界清除。只读、作用域明确的上下文也可以评估 ScopedValue。

参考资料

• Oracle Java Virtual Threads
• Oracle ThreadLocal API
• Oracle ScopedValue API
• OpenJDK JEP 444: Virtual Threads