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

ThreadLocal 的问题，在虚拟线程上被放大01

ThreadLocal 是「每个线程一份可变副本」。平台线程数量有限时，这点内存不算什么；虚拟线程可以轻松创建几十万个，每个线程的 ThreadLocalMap 都会放大开销。更麻烦的是，忘记 remove() 会把上一次请求的值带到下一次。

private static final ThreadLocal<User> CURRENT = new ThreadLocal<>();

void handle(Request req) {
    CURRENT.set(req.user());
    try {
        service.handle(req);
    } finally {
        CURRENT.remove(); // 少写一次就泄漏
    }
}

• 内存：每个虚拟线程一份副本；线程越多，ThreadLocalMap 总量越大。
• 清理：没有编译器保证 remove；线程复用或长生命周期虚拟线程会串请求。
• 可变性：任何被调用方都能 set，数据流难以推理。
• 继承：InheritableThreadLocal 在创建线程时复制，语义与结构化任务并不一致。

API：where / run / call02

ScopedValue.newInstance() 创建键，键通常声明为 static final。ScopedValue.where(key, value) 返回 Carrier；Carrier.run(Runnable) 无返回值，Carrier.call(CallableOp) 可以返回值并抛受检异常。

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");

        try {
            USER.orElse(null);
        } catch (Exception e) {
            System.out.println("orElse(null) -> " + e.getClass().getSimpleName());
        }

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

javac --release 25 ScopedValueDemo.java
java ScopedValueDemo

before -> <unbound>
inside -> alice
nested -> bob
restored -> alice
child virtual -> <unbound>
after -> <unbound>
orElse(null) -> NullPointerException
call returns carol

• get() 未绑定抛 NoSuchElementException；需要默认值用 orElse，需要业务异常用 orElseThrow。
• JDK 25 起 orElse(null) 直接抛 NullPointerException（JEP 506 的收口变化）。
• Carrier.call 的 lambda 目标类型是 ScopedValue.CallableOp，源码上仍可写 () -> ...。
• 键不要按请求动态创建；键是身份，不是字符串名。

继承边界：结构化 fork 会，手工线程不会03

这是 ScopedValue 最重要的行为边界：StructuredTaskScope.fork 创建的子任务会继承当前绑定；Thread.ofVirtual().start 和 ExecutorService.submit 不会。原因不是虚拟线程不继承，而是绑定传播由结构化作用域在 fork 时完成。

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())) {
                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 ScopedStructuredDemo.java
java --enable-preview ScopedStructuredDemo

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

生命周期：安装、恢复与异常04

实现上，当前绑定是一条不可变快照链：where 生成 Carrier，run/call 安装快照，退出时在 finally 中恢复旧快照。因为快照只读，嵌套、恢复和跨线程传递都不需要加锁。

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

    static String checked() throws Exception {
        return "checked " + USER.get();
    }

    public static void main(String[] args) throws Exception {
        System.out.println("carrier.get=" +
                ScopedValue.where(USER, "dave").get(USER));
        System.out.println("bound after carrier=" + USER.isBound());

        try {
            ScopedValue.where(USER, "x").run(() -> {
                throw new IllegalStateException("boom");
            });
        } catch (IllegalStateException e) {
            System.out.println("caught=" + e.getMessage());
        }
        System.out.println("bound after exception=" + USER.isBound());

        System.out.println(ScopedValue.where(USER, "eve")
                .call(ScopedExtra::checked));
    }
}

carrier.get=dave
bound after carrier=false
caught=boom
bound after exception=false
checked eve

• 异常退出同样会恢复：run/call 用 try/finally 恢复旧快照，不需要你写 remove。
• Carrier.get(key) 只读取 Carrier 上的临时绑定，不安装到线程；适合框架或测试。
• 嵌套 where 安装更短的链，内层优先；内层退出后外层值恢复。
• 绑定会持有值的强引用，直到作用域结束；不要在作用域里绑定不再需要的大对象。

落地：请求边界与迁移05

典型用法是在 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 currentUser() {
    return CURRENT_USER.orElseThrow(UnauthorizedException::new);
}

• 在入口绑定，在入口结束；不要在领域方法里随手 where，否则作用域碎片化。
• 绑定值用不可变对象；不要绑定可变实体再在作用域内修改它。
• 日志 MDC 底层通常仍是 ThreadLocal，ScopedValue 不会自动写入；需要适配层或手动同步。
• 面向 25 的代码只使用 where(...).run/call，不要再用 21 的 runWhere/callWhere/getWhere。

版本边界BOUNDARY

这张表比 API 本身更值得记。写代码时先确认你的运行时版本。

费曼自检SELF CHECK

先合上页面，用自己的话回答，再展开对照。能讲出因果和反例，才算真正掌握。