Scoped Values 上下文怎么配置或排查

把请求编号、租户或安全身份一路塞进方法参数，调用链一长就会变得难维护。ScopedValue 适合解决“调用方绑定、下游只读”的上下文传递问题：先在请求边界用 ScopedValue.where(key, value) 建立动态作用域，业务方法内部再用 get() 读取；作用域结束后绑定会自动恢复，不需要像 ThreadLocal 那样手动清理。

官方 API 文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/ScopedValue.html

先确认 JDK 版本和 ScopedValue API 形态

ScopedValue 在 Java 21 中还是预览能力，后来经历了多次 API 调整，Java 25 才以正式 API 形态出现。排查“方法不存在”时，先看 java -version 和项目的编译目标，不要只看 IDE 自动补全。当前写法是先创建 key，再通过 carrier 绑定：

// key 只作为上下文访问能力，不把它暴露给无关模块
private static final ScopedValue REQUEST_ID = ScopedValue.newInstance();

// 无返回值用 run；需要返回结果时，用 carrier.call(...) 包住计算
ScopedValue.where(REQUEST_ID, "req-20260913-01")
        .run(() -> service.handle());

旧资料中可能出现 runWhere、callWhere 或不同包名，那是预览阶段的 API 形态。项目锁定 JDK 21 时，应以该 JDK 的 API 和预览编译参数为准；升级到 Java 25 后再统一改成 where 返回的 Carrier 形式。

在请求边界绑定上下文，在业务层只读

绑定位置应该靠近一次请求、一次任务或一次回调的入口。中间层不必为了传递请求编号修改每个方法签名，只有持有同一个 key 的代码才能读取它。多个上下文可以链式绑定，但数量不要无限增加，多个值更适合收进一个不可变 record。

// 业务层只读必需上下文；缺失时快速暴露调用方漏绑问题
static void handle() {
    String requestId = REQUEST_ID.get();
    audit("request=" + requestId);
}

// 同一 key 的嵌套绑定只在内层生效，退出后自动回到外层值
ScopedValue.where(REQUEST_ID, "outer")
        .run(() -> ScopedValue.where(REQUEST_ID, "inner")
                .run(() -> handle()));

上例中 handle() 读到的是 inner，内层 run 返回后外层仍是 outer。这正是“有边界的上下文”与可长期存留的线程局部变量的关键区别。

用 isBound、orElse 和嵌套绑定定位读取问题

不要一看到异常就把所有 get() 换成默认值。先按业务语义选读取方式：

isBound() 适合日志或断言，不应成为把所有错误吞掉的开关。若异常只在某个分支出现，记录进入该分支时的线程、绑定入口和嵌套层级，通常比盲目加默认值更快定位。

把线程切换和结构化并发列入排查清单

绑定是按线程生效的。把任务提交给一个普通线程池后，不能把它当成自动继承上下文的证明；子线程读不到值时，先检查 where(...).run(...) 是否包住了真正执行的代码。需要把上下文传给子任务时，优先使用结构化任务作用域，并在创建作用域时确认绑定已经存在。

共享到子任务的值还应是不可变对象，或由同步机制保护。可以按下面顺序排查：

1. 确认运行时 JDK 与编译目标一致，排除预览 API 混用。
2. 在最外层确认 isBound()，再沿调用链找第一个读取点。
3. 检查是否发生了普通线程切换，以及结构化任务作用域是在绑定前还是绑定后创建。
4. 检查嵌套 where 是否只是临时重绑定，避免把内层值误认为全局状态。

这套顺序能把“API 不匹配”“入口漏绑定”“当前线程不对”和“嵌套值覆盖”分开，通常不需要先改业务逻辑。

相关问题

ScopedValue 未绑定时为什么不是 null？

get() 在当前线程没有绑定时抛出 NoSuchElementException，因为它表达的是“这里必须有上下文”。可选场景请显式使用 orElse。

ScopedValue 能完全替代 ThreadLocal 吗？

不能一概替代。单向、短生命周期的调用链上下文适合 ScopedValue；需要在线程生命周期内反复可变的状态，仍要重新评估 ThreadLocal 或其他状态管理方式。

为什么嵌套绑定退出后值会变回去？

嵌套绑定只覆盖内层动态作用域，内层操作正常返回或抛异常后，外层绑定自动恢复，这也是它避免残留状态的设计。