ScopedValue 是为虚拟线程设计的上下文传递原语，不依赖线程身份、不跨线程传播，声明须 static final，绑定须在 Scope.open() 作用域内，get() 返回 null 表示上下文未建立，异步操作需手动重建作用域。
ScopedValue 不是 ThreadLocal 的“升级版”，而是为虚拟线程重新设计的上下文传递原语：它不依赖线程身份，不维护哈希表，不强引用值，也不跨线程传播——用错一次，JVM 就会悄悄把你钉在平台线程上跑。
ScopedValue 声明和绑定必须严格匹配作用域生命周期
ScopedValue 实例本身无状态，但它的值只在 Scope.open() 创建的作用域内有效。声明时必须是 static final，否则无法被 JVM 识别为作用域边界锚点；绑定动作绝不能出现在作用域外，否则抛 IllegalStateException: not in scope。
- ✅ 正确写法：
private static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();
在 filter 或 handler 入口处：try (var scope = Scope.open()) {<br> scope.set(TRACE_ID, request.getHeader("X-Trace-ID"));<br> handleRequest(request);<br>} - ❌ 常见错误：在 Spring Bean 构造器里调用
TRACE_ID.set("xxx")→ 立即失败；或在@PostConstruct中绑定 → 值永远不可见 - ⚠️ 注意：
scope.set()是唯一安全的绑定方式；ScopedValue.where().run()是等价替代，但仅适用于单值、单层场景
ScopedValue.get() 返回 null 不代表出错，而是作用域未开启或已退出
不同于 ThreadLocal.get() 总会返回一个（可能是默认）值，ScopedValue.get() 在未绑定时明确返回 null。这不是 bug，而是设计信号：你正在代码路径中访问了一个尚未建立上下文的位置。
- 典型现象：日志中
[%X{traceId}]突然为空、链路追踪断开、MDC 丢失 —— 多半是某处异步调用跳出了作用域 - Spring AOP 切面若运行在新线程（如
@Async），TRACE_ID.get()必然为null，必须在切面内部手动重建作用域 - 不要对
null做空值兜底（如 fallback 到 UUID），这会掩盖作用域漏绑问题；应配合监控告警，在get()返回null且预期非空时触发告警
CompletableFuture 和线程池任务中 ScopedValue 自动失效
ScopedValue 默认不继承、不跨线程传播。任何显式切换执行线程的操作（包括 supplyAsync()、submit()、ForkJoinPool 调度）都会导致原作用域值不可见，并可能触发虚拟线程“钉住”（pinning）——JVM 强制将该任务调度到平台线程执行，彻底失去虚拟线程优势。
- ❌ 错误示例：
ScopedValue.where(TRACE_ID, "req-123").run(() -> {<br> CompletableFuture.supplyAsync(() -> {<br> return "got: " + TRACE_ID.get(); // → null<br> });<br>}); - ✅ 正确做法：在异步任务内部显式重建作用域：
String traceId = TRACE_ID.get();<br>CompletableFuture.supplyAsync(() -> {<br> return ScopedValue.where(TRACE_ID, traceId).run(() -> {<br> return "got: " + TRACE_ID.get(); // → req-123<br> });<br}); - ⚠️ 关键限制：不能用反射、字节码增强或动态代理绕过作用域检查，JVM 会拒绝卸载虚拟线程，造成 carrier thread 长期占用
日志框架 MDC 集成不是开箱即用，必须显式启用 ScopedValue 支持
Logback 和 Log4j2 默认仍使用 ThreadLocal 实现 MDC，直接替换 ScopedValue 后，所有 %X{key} 占位符都会输出空字符串，且不会报错——这是最隐蔽的迁移失败点。
- Logback：需升级至
logback-classic 1.5.0+，并在logback-spring.xml中启用ScopedMDCFilter，否则日志上下文全丢 - Log4j2：需配置
ThreadContextMap使用org.apache.logging.log4j.core.util.ScopedValueThreadContextMap，替换默认的ThreadLocalMap - 第三方库（如 Sentry、Micrometer）若内部硬编码依赖
MDC或ThreadLocal，需确认其是否已适配 JDK 21+ ScopedValue；否则仍得保留部分ThreadLocal兜底
真正难的不是写对那几行 scope.set()，而是让整个调用链——从网关入口、到异步回调、再到日志输出——全部落在同一个作用域语义下。一旦某个中间件、某个 SDK、某段反射调用绕开了作用域边界，ScopedValue 就会静默退化，而你只会看到 traceId 消失、内存缓慢上涨、GC 频繁——这些都不是报错，而是系统在用沉默告诉你：作用域断了。
