ScopedValue 是为虚拟线程设计的上下文机制，非 ThreadLocal 升级版；必须在 Scope.open() 内绑定，不支持提前 set()，不可跨作用域访问，需显式 fork 传递，且日志监控等中间件须适配。
ScopedValue 不是 ThreadLocal 的“升级版”，而是为虚拟线程重新设计的上下文传递机制——它不兼容 ThreadLocal 的使用惯性，强行套用会直接引发 IllegalStateException: not in scope 或数据不可见，尤其在 Spring Boot 3.2+ 启用虚拟线程后，ThreadLocal 已成为内存泄漏和 OOM 的确定性风险源。
ScopedValue 必须在 Scope.open() 内绑定，不能提前 set()
常见错误是把 ScopedValue.set() 当作 ThreadLocal.set() 那样在拦截器或 AOP 中随意调用。ScopedValue 没有全局 set 方法，所有绑定必须发生在 Scope.open() 创建的作用域内部，否则抛出异常。
- ❌ 错误：在 Spring
HandlerInterceptor.preHandle()中直接调用traceId.set("xxx")—— 这会报IllegalStateException - ✅ 正确：用
Scope.open()包裹整个请求处理链，例如在Filter或 WebMvc 的WebMvcConfigurer入口处开启作用域 - ⚠️ 注意：
Scope.open()是 try-with-resources 结构，必须配合try (var scope = Scope.open())使用，不能只声明不进入作用域
Spring Boot 中需绕过默认线程模型，显式控制作用域生命周期
Spring Boot 默认的 MVC 执行线程（如 Tomcat 线程）与虚拟线程解耦，Scope.open() 开启的作用域不会自动穿透到异步回调、@Async 或 CompletableFuture 中。你不能依赖“线程继承”来传递值。
- ❌ 错误：在
@Async方法里直接调用traceId.get()—— 返回null，因为新虚拟线程不在原Scope内 - ✅ 正确：用
scope.fork(() -> {...})或StructuredTaskScope显式派生子任务，值会自动继承；或在 fork 前手动提取并重绑定 - ? 实操建议：在 WebMvc 的
WebMvcConfigurer.addInterceptors()之后，用Filter封装Scope.open()，并在doFilter()中完成所有绑定，避免拦截器与 Filter 作用域错位
ScopedValue 实例必须 final 声明，且不能复用已绑定的值
ScopedValue 本身是轻量的工厂对象，但它的实例一旦被用于 scope.set()，就不能再被其他作用域“覆盖”或“重设”。每个作用域内只能绑定一次，且不可变。
- ❌ 错误：定义
static final ScopedValue后，在多个并发请求中反复调用USER = ScopedValue.newInstance(); scope.set(USER, "u1")→scope.set(USER, "u2")—— 第二次调用会失败 - ✅ 正确：一个
ScopedValue实例可被多个并发作用域安全复用，但每次scope.set()只能调用一次，且必须在同一个scope实例内 - ? 提示：推荐将
ScopedValue定义为public static final，放在配置类或常量类中；绑定逻辑统一收口到作用域开启处，避免分散在各处
日志、监控、AOP 等中间件需适配 ScopedValue 获取方式
Logback、SLF4J MDC、Micrometer、Spring AOP 切面等默认基于 ThreadLocal 实现，无法直接读取 ScopedValue。不改造就会导致日志丢失 traceId、指标维度缺失、AOP 中上下文为空。
- ❌ 错误：直接在
@Around切面中写traceId.get()—— 多数情况下返回null，因为切面执行线程可能已脱离原始作用域 - ✅ 正确：在作用域开启时，把关键值（如
traceId、tenantId）注入到MDC，或封装为Supplier传入切面；对 Logback，需升级到支持ScopedValue的 1.5.0+ 版本并启用ScopeMDCFilter - ⚠️ 关键点：ScopedValue 的值获取必须发生在同一
Scope实例内，跨方法调用不自动传递，必须显式透传或重新绑定
最易被忽略的是作用域边界的“隐形断裂”：哪怕只在一个 CompletableFuture.supplyAsync() 或 VirtualThread.start() 调用中漏掉 scope.fork()，上下文就彻底丢失，且无任何编译或运行时警告。这种问题在线上表现为偶发性日志断链或权限校验失败，排查成本极高。
