外观
21 - 并发上下文传播与 ScopedValue
版本说明:ThreadLocal 部分适用 JDK 8+;Scoped Values 在 JDK 25 通过 JEP 506 定稿。需要兼容旧 JDK 的库不能直接假定该 API 可用。
摘要
请求入口记录了租户和 TraceId,为什么把任务交给线程池后,下游却读不到,甚至读到了上一个请求的值?理解这类问题,先要区分方法调用和任务执行:同一个请求的代码,不一定始终在同一个线程上运行。
上下文是处理请求时需要随调用传递的信息,例如租户标识、安全身份和 TraceId(关联同一请求链路的追踪标识)。ThreadLocal 为每个线程保存各自的值,不会因为两个任务属于同一请求,就自动在执行它们的线程之间传递这些值。线程池又会复用工作线程;若上一个任务没有清理上下文,下一个任务可能读到旧值,这就是上下文污染。
本文先区分哪些信息可以传递,再解释线程池中的捕获、安装与恢复,最后介绍 ScopedValue 如何限制只读上下文的有效范围。
版本演进
| JDK | JEP | 状态 |
|---|---|---|
| 20 | JEP 429 | Incubator |
| 21 | JEP 446 | Preview |
| 22 | JEP 464 | 第二次 Preview |
| 23 | JEP 481 | 第三次 Preview |
| 24 | JEP 487 | 第四次 Preview |
| 25 | JEP 506 | 正式定稿 |
Incubator(孵化)和 Preview(预览)表示 API 仍处于演进阶段。JDK 25 代码使用 ScopedValue 不需要 --enable-preview;JDK 21–24 的对应版本则属于预览 API,需要匹配该 JDK 的编译和运行参数。不同阶段的 API 不能假定源码或二进制兼容。
1. 先区分三类“上下文”
| 类型 | 示例 | 推荐方式 |
|---|---|---|
| 业务输入 | tenantId、userId、请求 Deadline | 优先显式参数或不可变请求对象 |
| 横切观测 | TraceId、MDC 标签 | 受控的捕获、安装与恢复 |
| 线程绑定资源 | Spring 事务连接、Session | 不应复制到任意子线程 |
业务输入决定这次操作要做什么,显式传入能让依赖在方法签名中可见。Deadline 是请求的截止时间,用于限制任务还能执行多久。横切观测是多个业务层都需要的日志、追踪等信息;MDC(Mapped Diagnostic Context,映射诊断上下文)用于让日志携带请求标签,适合在受控范围内安装和恢复。
线程绑定资源则包含执行状态。这里的 Session 指框架管理的数据库或持久化会话。复制 TraceId 通常合理,但复制事务管理器内部的 ThreadLocal,可能只是让多个线程引用同一个连接或 Session,并没有建立一个新事务。这既可能并发使用非线程安全资源,也可能破坏原有事务边界。因此,应按信息的语义决定传播方式,而不是复制全部 ThreadLocal。
2. 线程池传播必须是快照
快照是提交任务时选定的上下文值。提交线程先捕获它,执行任务的线程再临时安装它,任务退出时恢复该线程原先的值。这样,任务使用的是提交时的上下文,也不会把自己的上下文留给后续任务。
下面是传播流程示意,不是可直接运行的完整程序。ContextSnapshot 和 context 是自定义抽象,不是 JDK API;假定 capture 捕获当前线程的上下文,install 安装指定快照,restore 恢复原状态(包括原本没有绑定值的情况),executor 和 task 已由外围代码提供:
java
ContextSnapshot captured = context.capture();
executor.execute(() -> {
ContextSnapshot previous = context.capture();
try {
context.install(captured);
task.run();
} finally {
context.restore(previous);
}
});第一个 capture() 在提交线程执行,确定任务要携带的值;第二个在执行线程中保存原状态。若等到工作线程开始执行才捕获,读到的可能是工作线程自己的旧值,而不是提交者的值。
快照中的值应不可变,或明确复制策略。若快照仅引用一个可变 Map,提交者在任务排队期间修改它,任务读到的内容就可能变化;多个线程无同步地读写它,还可能产生数据竞争。
finally 让任务正常返回或抛出异常时都执行恢复。恢复原值比无条件清空更适合嵌套调用:外层任务原本已有上下文,内层结束后应继续使用外层值。任务提交被拒绝、尚未开始执行时,不应安装上下文;取消与拒绝是否会触发包装代码,还要结合执行器和任务状态检查。
3. CompletableFuture 的阶段边界
CompletableFuture 可以把多个处理步骤串成完成阶段,例如先查询,再转换结果。阶段是执行动作的边界,创建 Future 并不意味着后面的动作都在创建线程上运行。
不带 Async 的阶段可能由完成前一阶段的线程执行;带 Async 的阶段则由指定 Executor(执行器)或默认执行器执行。因此,“创建 Future 的线程”不足以推断上下文在哪个线程可见。即使前一阶段已经安装上下文,也不能据此假定后一阶段切换线程后仍能读取它。
每个异步边界都应显式选择 Executor 和传播策略。完整编排语义见 10 - CompletableFuture 异步编排。
4. ScopedValue 解决什么
ScopedValue 将一个键与一个值绑定,并把绑定限制在一次受控调用范围内。被调用方法可以通过同一个键读取值,无需每层方法都增加参数,这就是隐式传递;但它没有 ThreadLocal 那样的 set(),不能在任意位置直接改写当前绑定并遗忘清理。
下面是 JDK 25 的局部使用片段,省略了外围类;假定已有请求上下文类型 RequestContext、对象 context 和处理方法 handleRequest():
java
private static final ScopedValue<RequestContext> REQUEST =
ScopedValue.newInstance();
ScopedValue.where(REQUEST, context).run(() -> handleRequest());REQUEST 是用于读取上下文的键,where(REQUEST, context) 指定本次绑定,run 执行需要该绑定的代码。handleRequest() 及其调用的方法可通过 REQUEST.get() 读取上下文,前提是执行时该键已绑定。
绑定只在 run 的动态调用范围内可见:这里的范围包括回调执行期间调用的下游方法,不只是源代码中的花括号。退出该范围后,本次绑定自动失效,因此无需手工清理。只读指的是绑定不能通过 set() 改写;若绑定的对象本身可变,其内部状态仍可能被修改,因此优先绑定不可变值。不要把“绑定只读”理解为“对象自动变得线程安全”。
5. 与虚拟线程和结构化并发的关系
虚拟线程是由 JDK 调度的轻量线程,适合采用一个任务对应一个虚拟线程的执行方式。ScopedValue 适合在这种方式下提供只读请求上下文,也能配合结构化并发:父任务创建子任务,并在一个明确范围内管理它们的完成、失败和取消。
“任务在绑定范围内提交”不等于“任务执行时自动拥有绑定”。ScopedValue 不会自动把值传播到任意 Executor 中的无关任务;传播行为必须按所用 API 和目标 JDK 文档确认。任务若脱离父调用独立运行,还需要单独考虑上下文的有效期。
结构化并发 API 在 JDK 25 仍是预览,而 ScopedValue 已在 JDK 25 定稿,两者的稳定性状态不能混为一谈。父子任务取消与作用域边界见 18 - 结构化并发与任务生命周期。
这也意味着一个 JDK 25 应用可以稳定使用 ScopedValue,同时完全不启用结构化并发。不要为了上下文传播而无条件引入另一项预览特性。
6. API 边界与迁移策略
ScopedValue 适合由调用栈向下提供只读上下文,不适合替代:
- 需要在任意位置更新的线程局部缓存;
- 跨无关 Executor 长期保存的会话状态;
- 可变事务资源和数据库连接;
- 需要持久化或跨进程传播的 Trace/租户信息。
前两类状态需要独立的更新或存活规则,不能仅由一次调用范围管理;后两类分别涉及资源管理和进程间传输,也超出了只读绑定的职责。
需要同时支持 JDK 17 和 JDK 25 的库,可以继续提供显式上下文参数或抽象传播接口,由 JDK 25 适配层使用 ScopedValue。公共 API 是使用者需要引用的方法签名和类型;不要通过反射把预览或新版本类型泄漏到公共 API,否则旧 JDK 使用者仍可能受到类型可用性的限制。
7. 安全与资源边界
- 不把访问令牌、密码等敏感值写入会被日志自动输出的 MDC;
- 不传播已经过期的 Deadline,子任务应根据截止时间计算剩余预算,而不是重新获得完整超时时长;
- 不复制连接、事务或非线程安全 Session;
- 明确异步任务结束后上下文是否仍有业务意义;
- 对线程池、虚拟线程和嵌套调用分别做污染测试。
Spring 声明式事务通常依赖线程绑定资源,跨线程边界应重建事务而不是复制内部状态,参见 Spring 11 - Spring 声明式事务执行链。
8. 排障方法
先判断问题发生在哪一步:提交时没有捕获正确值、执行时没有安装、退出时没有恢复,还是传递了不该共享的资源。然后按以下线索检查:
- 记录上下文的捕获线程、执行线程和任务标识;
- 检查传播包装是否覆盖异常、取消、拒绝和嵌套执行;
- 用单线程池连续执行不同租户任务,主动检测旧值污染;单线程池能让这些任务复用同一工作线程,便于暴露清理遗漏;
- 发现 Trace 断链(前后操作无法关联到同一追踪链路)时,先确认异步边界和 Executor,再检查采样策略;采样决定哪些追踪记录被保留;
- 发现内存滞留时,沿线程到 ThreadLocalMap 的引用链检查,方法见 B - ThreadLocal 内存泄漏与上下文污染。
9. 总结
上下文传播不是复制全部 ThreadLocal,而是按语义跨越明确的任务边界。
- 业务输入优先显式传递,观测上下文使用可恢复快照。
- 事务连接等线程绑定资源不能作为普通上下文复制。
- JDK 25 的 ScopedValue 适合受控调用范围内的只读绑定,不能据此假定任意异步任务都能继承上下文。
本文仅完成文本改写和静态自查,未编译或运行示例,也未独立核验 JDK、JEP 或 Spring 的一手资料。版本演进、API 契约和具体传播行为仍需结合目标 JDK 与框架版本核对;上述排障步骤是验证建议,不是已执行的测试记录。