Scoped Values：有作用域的不可变上下文

API 形状与 JDK 21 的预览差异01

public final class ScopedValue<T> {
    public static <T> ScopedValue<T> newInstance();
    public T get();                       // 未绑定抛 NoSuchElementException
    public boolean isBound();
    public T orElse(T other);
    public <X extends Throwable> T orElseThrow(Supplier<? extends X> ex);

    public static <T> Carrier where(ScopedValue<T>, T);
}

public final class ScopedValue.Carrier {
    public <T> Carrier where(ScopedValue<T>, T); // 叠加多个绑定
    public <T> T get(ScopedValue<T>);
    public <R> R call(Callable<? extends R>) throws Exception;
    public void run(Runnable);
}

static final ScopedValue<String> USER = ScopedValue.newInstance();
static final ScopedValue<String> TENANT = ScopedValue.newInstance();

ScopedValue.where(USER, "alice")
        .where(TENANT, "acme")
        .run(() -> {
            System.out.println(USER.get() + " @ " + TENANT.get());
            // 不进入作用域也能读 Carrier 上的临时绑定
            System.out.println(ScopedValue.where(USER, "bob").get(USER));
        });

JDK 21 还提供了 runWhere、callWhere、getWhere 三个静态便捷方法，但它们在后续预览中已被移除。面向 25 的代码只应使用 ScopedValue.where(...).run/call 这一套稳定形状。

绑定如何随作用域和虚拟线程移动02

可以把当前线程的 ScopedValue 绑定理解成一个不可变快照链：每次 where 生成新的绑定快照；进入 run/call 时安装，退出时在 finally 中恢复旧快照。因为快照只读，嵌套、恢复和跨线程传递都不需要加锁。

1. where(USER, "alice") 创建一个 Carrier，记录键值对。
2. run 在当前线程安装这个 Carrier 对应的绑定快照。
3. lambda 内 get() 沿快照链查找；嵌套 where 安装更短的链，优先命中内层。
4. lambda 正常返回或抛异常，run 都会恢复进入前的快照。
5. StructuredTaskScope.fork 在创建子任务时捕获当前快照，子任务从该快照开始执行。
6. 手工 Thread.ofVirtual().start 没有这个捕获步骤，新线程从空绑定开始。

对虚拟线程来说，绑定快照属于线程/续体的执行状态；虚拟线程挂起再恢复时，绑定仍然有效。这也是为什么作用域内的 get() 不需要额外同步。

从 ThreadLocal 迁移：映射与保留场景03

// Before
private static final ThreadLocal<User> USER = new ThreadLocal<>();

void handle(Request req) {
    USER.set(req.user());
    try { service.handle(req); }
    finally { USER.remove(); }
}

// After
private static final ScopedValue<User> USER = ScopedValue.newInstance();

void handle(Request req) throws Exception {
    ScopedValue.where(USER, req.user())
            .run(() -> service.handle(req));
}

日志 MDC 是最容易被忽略的迁移点：很多日志框架的 MDC 底层仍然是 ThreadLocal。ScopedValue 不会自动填充 MDC；如果日志需要 traceId，要在绑定作用域时同步设置/清理 MDC，或使用支持 ScopedValue 的日志适配层。

模式：在请求边界绑定上下文01

典型用法是在 HTTP / RPC 入口完成认证后绑定用户、租户和 traceId，领域代码只读，不再层层传参。绑定的生命周期就是一次请求。

static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();

Response handle(Request req) throws Exception {
    User user = authenticate(req);
    return ScopedValue.where(CURRENT_USER, user)
            .where(TRACE_ID, req.traceId())
            .call(() -> service.handle(req));
}

// 深层服务代码
User user() {
    return CURRENT_USER.orElseThrow(() -> new UnauthorizedException());
}

• 在入口绑定，在入口结束；不要在领域方法里随手 where，否则作用域会碎片化。
• 绑定值用不可变对象；不要绑定可变实体，然后在作用域内修改它。
• 异步任务如果必须携带上下文，用 StructuredTaskScope；不要把手工作业的线程当成自动继承。
• 需要默认值的读取用 orElse，需要强制认证的读取用 orElseThrow。

可运行示例：嵌套、恢复与手工线程02

import java.util.concurrent.*;

public class ScopedValueDemo {
    static final ScopedValue<String> USER = ScopedValue.newInstance();

    static void show(String label) {
        System.out.println(label + " -> " +
                (USER.isBound() ? USER.get() : "<unbound>"));
    }

    public static void main(String[] args) throws Exception {
        show("before");

        ScopedValue.where(USER, "alice").run(() -> {
            show("inside");
            ScopedValue.where(USER, "bob").run(() -> show("nested"));
            show("restored");

            Thread child = Thread.ofVirtual().start(() -> show("child virtual"));
            try {
                child.join();
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
        });

        show("after");
    }
}

javac --enable-preview --release 21 ScopedValueDemo.java
java --enable-preview ScopedValueDemo

before -> <unbound>
inside -> alice
nested -> bob
restored -> alice
child virtual -> <unbound>
after -> <unbound>

输出验证了三件事：嵌套绑定会遮蔽外层；退出内层恢复外层；手工启动的虚拟线程看不到父作用域的绑定。

可运行示例：结构化子任务继承绑定03

import java.util.concurrent.*;

public class ScopedStructuredDemo {
    static final ScopedValue<String> USER = ScopedValue.newInstance();

    static String current() {
        return USER.isBound() ? USER.get() : "<unbound>";
    }

    public static void main(String[] args) throws Exception {
        ScopedValue.where(USER, "alice").run(() -> {
            try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
                var inherited = scope.fork(ScopedStructuredDemo::current);
                scope.join().throwIfFailed();
                System.out.println("structured subtask=" + inherited.get());
            } catch (Exception e) {
                throw new RuntimeException(e);
            }

            try {
                Thread manual = Thread.ofVirtual().start(
                        () -> System.out.println("manual virtual thread=" + current()));
                manual.join();
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
        });

        String outside = ScopedValue.where(USER, "bob").call(
                () -> "call returns " + USER.get());
        System.out.println(outside);
    }
}

javac --enable-preview --release 21 ScopedStructuredDemo.java
java --enable-preview ScopedStructuredDemo

structured subtask=alice
manual virtual thread=<unbound>
call returns bob

如果业务必须让所有并发子任务都看到上下文，就把它们放进一个 StructuredTaskScope，而不是手工创建线程或提交到共享线程池。

常见坑04

• 以为手工线程会继承：Thread.ofVirtual().start、ExecutorService.submit 都不会自动继承；只有结构化 fork 会。
• 绑定可变对象：ScopedValue 只保证绑定不可变，不保证对象内部状态不可变。
• 在领域逻辑里到处 where：作用域应当由请求/任务边界统一管理，否则很难推理生命周期。
• 依赖 JDK 21 的预览便捷方法：runWhere/callWhere/getWhere 在 25 已移除。
• 忘记 MDC：日志框架的 MDC 仍是 ThreadLocal，ScopedValue 不会自动同步。
• 把 ScopedValue 当线程池使用：它只传递上下文，不创建、不调度任务。

先猜再看01

费曼自检：作用域与传播02