Java Virtual Threads 怎样避免线程本地变量滥用

Java Virtual Threads 让大量阻塞 I/O 任务可以用“一个任务一个虚拟线程”的方式表达，但这不等于每个线程都适合挂一份状态。避免线程本地变量滥用的核心是先分清：请求元数据可以短时传播，连接、缓冲区、客户端和可变业务状态必须回到任务或资源管理器的生命周期。

官方资料：https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html

迁移时保留少量、只读、请求级的上下文；把资源创建与关闭放在任务边界，把连接数和外部并发交给连接池或限流器。ThreadLocal 不是资源池，也不是虚拟线程的共享缓存。

目标和边界：先给 ThreadLocal 字段分类

Virtual Thread 不是固定绑定某个操作系统线程的轻量版平台线程。阻塞 I/O 时，运行时可以挂起虚拟线程并释放承载线程，因此一个 JVM 可能同时拥有非常多的虚拟线程。Oracle 文档也特别提醒：虽然虚拟线程支持 thread-local variables 和 inheritable thread-local variables，但使用前要谨慎。

可以把现有字段分成三类：

为什么每个虚拟线程都放一份状态容易失控

ThreadLocal 的值属于访问它的线程副本。线程存活期间，这份副本会继续存在；虚拟线程数量上升时，哪怕单个值不大，累计对象、引用链和初始化成本也会放大。更危险的是把连接、会话客户端或大缓冲区放进去：它们看似“线程隔离”，实际却绕过了资源池的容量和回收策略。

常见误区是把 ThreadLocal.remove() 当成万能修复。它只能清掉当前线程当前变量的值，不能解决值本身过大、继承成本、任务取消时未执行清理，或把资源池误当作线程缓存的问题。在线程池场景还要担心上一个任务的值泄漏到下一个任务；虚拟线程通常按任务创建，泄漏形态不同，但不代表可以无限绑定对象。

只读上下文：显式参数优先，ScopedValue 谨慎使用

如果下游方法真的需要 traceId，最容易审查的是显式参数。它让调用关系可见，也不会因为某个静态字段被悄悄读取而增加隐式依赖。只有当调用链很深、且数据确实是“调用者绑定、被调用者只读”时，才考虑 ScopedValue。

Java 21 中的 ScopedValue 仍是 preview API，需要启用预览特性。它按动态作用域绑定值，外层调用完成后绑定自动解除；Oracle API 文档还指出，相比 ThreadLocal，它更适合单向传输，因为远端被调用者不能直接设置调用者的值。

import java.lang.ScopedValue;

public final class RequestContext {
    // 只绑定不可变的请求元数据，不放连接或可变缓存。
    private static final ScopedValue META = ScopedValue.newInstance();

    public static void serve(RequestMeta meta) {
        // 绑定只覆盖本次调用，退出 lambda 后自动解除。
        ScopedValue.runWhere(META, meta, RequestContext::handle);
    }

    private static void handle() {
        // 下游只能读取当前作用域中的元数据，未绑定时立即暴露调用错误。
        RequestMeta meta = META.orElseThrow(() -> new IllegalStateException("缺少请求上下文"));
        audit(meta.traceId());
    }

    private static void audit(String traceId) {
        // 只记录短字符串，不借此缓存数据库连接或客户端实例。
        System.out.println("trace=" + traceId);
    }

    public record RequestMeta(String traceId, String tenant) {}
}

上面的选择仍有边界：ScopedValue 适合少量、短生命周期、只读的上下文；可变对象即使被放进 ScopedValue，也可能被下游修改。若参数只有一两层，直接传参通常更清楚。若需要跨线程结构化共享，还要保证对象不可变或自行同步。

资源生命周期：不要用 ThreadLocal 代替连接池

虚拟线程数量可以远大于数据库连接数、下游 HTTP 并发额度或文件描述符上限。资源控制应由连接池、客户端配置和明确的 Semaphore 完成，而不是给每个虚拟线程懒加载一份资源。

import java.sql.Connection;
import java.util.concurrent.Semaphore;

public final class QueryTask {
    // 许可数代表外部数据库允许的并发，不等于虚拟线程数量。
    private static final Semaphore DB_LIMIT = new Semaphore(32);

    public static Result query(DataSource dataSource, String sql) throws Exception {
        DB_LIMIT.acquire();
        try (Connection connection = dataSource.getConnection()) {
            // 连接由任务显式取得并关闭，避免藏在 ThreadLocal 中跨任务存活。
            try (var statement = connection.prepareStatement(sql)) {
                return read(statement.executeQuery());
            }
        } finally {
            // 无论查询成功、失败还是取消，都归还并发许可。
            DB_LIMIT.release();
        }
    }

    private static Result read(java.sql.ResultSet rows) throws Exception {
        // 示例只表示结果映射边界，不把 ResultSet 放进线程本地变量。
        return Result.from(rows);
    }

    public interface DataSource {
        Connection getConnection() throws Exception;
    }
    public record Result(String value) {
        static Result from(java.sql.ResultSet rows) { return new Result("按业务映射结果"); }
    }
}

这里的重点不是把许可数写死为 32，而是让它由数据库、连接池和下游服务容量共同决定。Virtual Threads 负责承载等待，不负责扩大外部资源上限。

推荐迁移流程和检查点

1. 列清单：记录每个 ThreadLocal 的类型、初始化方式、值大小、所有者和清理点；看见连接、客户端、大数组或可变缓存就先移出。
2. 缩短上下文：traceId、租户等只读元数据优先改为方法参数；调用链很深时再评估 Java 21 preview 的 ScopedValue。
3. 固定资源边界：在虚拟线程任务内取得资源，用 try-with-resources 关闭；连接池、Semaphore 和超时控制外部容量。
4. 验证异常路径：检查取消、超时、异常和早返回是否仍会释放资源；ThreadLocal 只在确有必要时配对 remove。

迁移后的判断标准不是“ThreadLocal 数量变成零”，而是每个字段都能回答三件事：谁拥有它、它最多存活多久、它在并发升高时会不会按虚拟线程数量复制。回答不清楚的字段，就不应继续放在隐式线程状态里。

常见问题

Virtual Threads 能不能完全禁止 ThreadLocal？

不必一刀切。少量、短生命周期的请求元数据仍可能适合 ThreadLocal，但要明确清理和继承边界；资源对象、可变缓存和需要容量控制的外部客户端不应借此保存。

ScopedValue 是否已经可以无条件替代 ThreadLocal？

不能。Java 21 的 ScopedValue 是 preview API，部署链需要允许预览特性；它解决的是只读、单向、动态作用域传递，不是通用的可变状态容器或资源池。

速查表