Scoped Values 内部：绑定快照、作用域与传递边界

API 形状：Carrier 链与 CallableOp01

JDK 25 的 ScopedValue 是 java.lang 下的 final 类，没有公开构造器；键通过 newInstance() 创建。where 返回一个 Carrier，Carrier 可以继续叠加绑定，最后用 run 或 call 进入作用域。

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, X extends Throwable> R call(
            ScopedValue.CallableOp<? extends R, X>) throws X;
    public void run(Runnable);
}

Carrier.get(key) 可以在不进入 run/call 的情况下读取临时绑定；它不会让绑定泄漏到当前线程。下面的输出来自本机验证：读取 dave 之后，USER 仍然是未绑定状态。

System.out.println("carrier.get=" +
        ScopedValue.where(USER, "dave").get(USER));
System.out.println("bound after carrier=" + USER.isBound());

carrier.get=dave
bound after carrier=false

CallableOp 是函数式接口，lambda 源码通常不用改；但方法签名从 Callable 变成了可抛受检异常的 CallableOp，依赖精确签名的反射或方法引用需要重新编译。ScopedValue 本身没有静态 call 方法，返回值只能通过 Carrier.call。

安装、恢复与 fork：一条不可变快照链02

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

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

ScopedValue.where(USER, "alice").run(() -> {
    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var future = executor.submit(
                () -> USER.isBound() ? USER.get() : "<unbound>");
        try {
            System.out.println("executor=" + future.get());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
});

executor=<unbound>

这条模型解释了两个常见误解：第一，ScopedValue 并不为每个线程复制一份值，值对象本身可以共享，复制的是绑定快照的引用；第二，作用域结束不是「清空一个线程局部变量」，而是恢复进入前的状态。没有 remove，因为不存在需要手动清理的线程局部槽位。

模式：在请求边界绑定上下文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，否则作用域会碎片化。
• 绑定值用不可变对象；不要绑定可变实体，然后在作用域内修改它。
• 需要默认值的读取用 orElse，需要强制认证的读取用 orElseThrow。
• 异步任务如果必须携带上下文，用 StructuredTaskScope；不要把手工线程当成自动继承。
• 日志 MDC 仍可能是 ThreadLocal；需要 traceId 时在绑定作用域时同步设置/清理，或使用支持 ScopedValue 的适配层。

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

如果任务必须看到上下文，把它放进 StructuredTaskScope，而不是手工创建线程或提交到共享线程池。下面的例子同时展示继承与不继承两条路径。

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 = StructuredTaskScope.open(
                    StructuredTaskScope.Joiner.<String>allSuccessfulOrThrow())) {
                var inherited = scope.fork(ScopedStructuredDemo::current);
                scope.join().forEach(
                        s -> System.out.println("structured subtask=" + s.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 --release 25 --enable-preview -d out ScopedStructuredDemo.java
java --enable-preview -cp out ScopedStructuredDemo

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

同一段代码里，结构化 fork 读到了 alice；手工虚拟线程读到 <unbound>；作用域外 where(USER, "bob").call(...) 正常返回值。继承语义由 fork 完成，不是由「虚拟线程」这个类型自动赋予。

常见坑03

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

合上页面，先回答01

版本与边界一页表02

如果只能记一句话：ScopedValue 约束的是可见范围，不是线程身份。它把「谁知道这个值」变成代码结构问题，而不是线程生命周期问题。