Java ScopedValue替代ThreadLocal的虚拟线程友好方案

在Java中，ThreadLocal 曾是线程隔离数据的常用工具，用于存储用户会话、数据库连接等上下文信息。但在虚拟线程时代，它暴露了内存泄漏和继承问题的缺陷。ThreadLocal 的值与线程实例绑定，虚拟线程是轻量级的，频繁创建和销毁会导致 ThreadLocal 的值无法被正确回收，造成内存泄漏。同时，子线程可以继承父线程的 ThreadLocal 值，这种不可预测的继承性也带来了风险。

为了解决这些问题，Java 19 引入了 ScopedValue。它提供了一种更安全、更高效的方式来在代码块中传递上下文信息，尤其适合虚拟线程环境。

1. 定义 ScopedValue 实例

首先，你需要定义一个 ScopedValue 实例。它通常被声明为 static final，以确保其唯一性和不可变性。

public class ContextHolder {
    // 定义一个用于存储用户ID的 ScopedValue
    public static final ScopedValue<String> USER_ID = new ScopedValue<>();
}

2. 在作用域内绑定值

接下来，使用 ScopedValue 的 runWhere 或 callWhere 方法来创建一个作用域，并在该作用域内绑定一个值。runWhere 用于执行 Runnable，callWhere 用于执行 Callable 并返回结果。

public class ScopedValueExample {
    public static void main(String[] args) {
        // 使用 runWhere 方法绑定值并执行代码块
        ScopedValue.runWhere(ContextHolder.USER_ID, "user-123", () -> {
            // 在这个代码块内部，ContextHolder.USER_ID.get() 将返回 "user-123"
            System.out.println("User ID in scope: " + ContextHolder.USER_ID.get());
        });
    }
}

runWhere 方法接受三个参数：

1. ScopedValue 实例。
2. 要绑定的值。
3. 一个 Runnable，表示作用域内的代码块。

3. 在作用域内访问值

在 runWhere 或 callWhere 的代码块内部，你可以通过 get() 方法安全地获取绑定的值。

ScopedValue.runWhere(ContextHolder.USER_ID, "user-123", () -> {
    // 在作用域内访问值
    String id = ContextHolder.USER_ID.get();
    System.out.println("Current user ID: " + id);
    // 调用其他方法，值会自动传递
    processRequest();
});

public static void processRequest() {
    // 即使在另一个方法中，只要在同一个作用域内，也能获取到值
    System.out.println("User ID in processRequest: " + ContextHolder.USER_ID.get());
}

关键点：get() 方法只能在已绑定的作用域内调用。如果在作用域外部调用，会抛出 ScopedValue.NotPresentException 异常。

4. ScopedValue vs. ThreadLocal：核心差异

为了更清晰地理解 ScopedValue 的优势，我们可以通过一个表格进行对比。

5. 完整示例：模拟请求处理

下面是一个完整的示例，模拟一个Web请求的处理流程，其中 ScopedValue 用于在各个处理层之间传递请求ID。

import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;

public class RequestProcessingExample {

    // 定义一个用于存储请求ID的 ScopedValue
    public static final ScopedValue<String> REQUEST_ID = new ScopedValue<>();

    public static void main(String[] args) {
        // 模拟接收到一个新请求
        String incomingRequestId = "req-789";

        // 使用 ScopedValue 绑定请求ID，并开始处理整个请求流程
        ScopedValue.runWhere(REQUEST_ID, incomingRequestId, () -> {
            System.out.println("Request received with ID: " + REQUEST_ID.get());
            // 调用服务层处理请求
            handleRequest();
        });
    }

    public static void handleRequest() {
        System.out.println("Handling request in service layer: " + REQUEST_ID.get());
        // 调用数据访问层
        fetchData();
    }

    public static void fetchData() {
        System.out.println("Fetching data in DAO layer: " + REQUEST_ID.get());
        // 模拟一个异步操作，使用虚拟线程
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            Subtask<String> subtask = scope.fork(() -> {
                // 在子任务中也能访问到父作用域的值
                System.out.println("Executing async task with request ID: " + REQUEST_ID.get());
                return "data-from-db";
            });

            scope.join(); // 等待子任务完成
            System.out.println("Async task result: " + subtask.get());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

运行结果：

Request received with ID: req-789
Handling request in service layer: req-789
Fetching data in DAO layer: req-789
Executing async task with request ID: req-789
Async task result: data-from-db

这个示例展示了 ScopedValue 如何优雅地在同步和异步代码（如 StructuredTaskScope）之间传递上下文，而无需担心内存泄漏或继承问题。

6. 处理嵌套作用域

当在已存在的作用域内再次调用 runWhere 时，会创建一个嵌套作用域。在内层作用域中，get() 方法会返回内层绑定的值。当内层作用域结束后，绑定的值会自动失效，外层作用域的值恢复。

public class NestedScopeExample {
    public static final ScopedValue<String> SCOPE_VALUE = new ScopedValue<>();

    public static void main(String[] args) {
        ScopedValue.runWhere(SCOPE_VALUE, "outer", () -> {
            System.out.println("Outer scope value: " + SCOPE_VALUE.get());

            // 在外层作用域内创建一个内层作用域
            ScopedValue.runWhere(SCOPE_VALUE, "inner", () -> {
                System.out.println("Inner scope value: " + SCOPE_VALUE.get());
            });

            // 内层作用域结束后，值恢复为外层的值
            System.out.println("Back to outer scope value: " + SCOPE_VALUE.get());
        });
    }
}

运行结果：

Outer scope value: outer
Inner scope value: inner
Back to outer scope value: outer

7. 与虚拟线程的集成

ScopedValue 的设计初衷就是为虚拟线程服务的。虚拟线程由 ForkJoinPool 调度，ScopedValue 的作用域绑定信息存储在 ForkJoinPool 的栈帧中。这使得 ScopedValue 在虚拟线程中能高效地传递上下文，避免了 ThreadLocal 的性能开销和内存问题。当你使用 Executor 提交任务时，ScopedValue 的上下文会自动传递给新创建的虚拟线程，实现真正的无感知传递。