在 Java 后端中,请求 ID、租户信息和日志上下文常被放进 ThreadLocal。但在线程复用、虚拟线程和结构化并发场景下,开发者需要重新思考:上下文属于某条线程,还是属于一次有明确生命周期的调用?JEP 506 已在 Java 25 正式交付 Scoped Values,提供了更清晰的只读绑定语义。本文对比 ThreadLocal、ScopedValue、虚拟线程与结构化并发,给出 JDK 25 可复现示例和 Spring 项目迁移边界。
技术栈:JDK 25、ScopedValue、虚拟线程、JUnit 5;结构化并发部分使用 Java 25 预览 API
一、ThreadLocal 的问题不是“不能用”
传统请求上下文通常这样维护:
private static final ThreadLocal<String> REQUEST_ID =
new ThreadLocal<>();
void handle(String requestId) {
REQUEST_ID.set(requestId);
try {
service();
} finally {
REQUEST_ID.remove();
}
}
在线程池中,工作线程可能被后续请求复用。遗漏 remove() 会让下一个请求读到旧值,产生日志串号或敏感上下文污染。但 ThreadLocal 仍适合需要线程局部可变状态的场景,不能简单认定它已经过时。
很多请求上下文真正需要的是:在一次调用范围内绑定一个只读值,调用结束自动恢复。 这才是 ScopedValue 的核心用途。
二、Java 25 ScopedValue 的基本语义
2.1 最小可运行示例
import java.lang.ScopedValue;
public class ScopedDemo {
private static final ScopedValue<String> REQUEST_ID =
ScopedValue.newInstance();
public static void main(String[] args) {
ScopedValue.where(REQUEST_ID, "req-001").run(() -> {
System.out.println(REQUEST_ID.get());
});
System.out.println(REQUEST_ID.isBound());
}
}
预期输出
req-001
false
where(KEY, value).run(…) 在动态作用域内建立绑定,退出后自动恢复先前状态;这里不需要手动 remove()。示例面向 Java 25 正式 API,无需 –enable-preview,但本次写作未实际执行。
2.2 版本边界不能混淆
| ThreadLocal | 正式 | 正式 | 正式 |
| 虚拟线程 | 尚无正式 API | 正式 | 正式 |
| ScopedValue | 不可用 | 预览 | JEP 506 正式 |
| StructuredTaskScope | 不可用 | 预览 | 仍为预览 |
ScopedValue 在 Java 25 正式,不等于结构化并发也正式。 后者仍需预览功能开关,且 API 相比早期预览版本发生变化。
三、构造请求级只读上下文
3.1 用 record 保存不可变身份快照
package demo.context;
import java.lang.ScopedValue;
public final class RequestContext {
public record Identity(String requestId, long tenantId) {}
public static final ScopedValue<Identity> CURRENT =
ScopedValue.newInstance();
private RequestContext() {}
public static Identity required() {
return CURRENT.get();
}
}
record 的字段不可重新赋值,但如果字段引用的是可变对象,ScopedValue 并不会自动让它线程安全。尽量绑定小型、不可变的数据快照。
3.2 在入口绑定,深层方法读取
package demo.context;
import java.lang.ScopedValue;
public final class OrderQuery {
public String loadOrder(long orderId) {
var identity = RequestContext.required();
return "request=" + identity.requestId()
+ ", tenant=" + identity.tenantId()
+ ", order=" + orderId;
}
public static void main(String[] args) {
var query = new OrderQuery();
var identity = new RequestContext.Identity("req-42", 1001L);
String result = ScopedValue
.where(RequestContext.CURRENT, identity)
.call(() -> query.loadOrder(88L));
System.out.println(result);
}
}
预期输出
request=req-42, tenant=1001, order=88
ScopedValue 能减少深层调用链中重复传递 requestId 的参数,但会引入隐式依赖。订单 ID、金额、分页参数仍应显式传递,不要把所有业务参数都塞进上下文。
四、嵌套绑定:退出后恢复外层值
import java.lang.ScopedValue;
public class NestedScope {
static final ScopedValue<String> LOCALE =
ScopedValue.newInstance();
public static void main(String[] args) {
ScopedValue.where(LOCALE, "zh-CN").run(() -> {
System.out.println(LOCALE.get());
ScopedValue.where(LOCALE, "en-US").run(() ->
System.out.println(LOCALE.get()));
System.out.println(LOCALE.get());
});
}
}
预期输出
zh-CN
en-US
zh-CN
内部作用域重新绑定同一个键,退出后外层绑定自动恢复。它不是对共享变量做 set;绑定关系遵循作用域嵌套。需要维护可变计数器、事务状态或异步任务进度时,应优先使用明确的业务状态对象或并发组件。
五、虚拟线程会自动继承父线程的 ScopedValue 吗?
不能因为一个线程是虚拟线程,就认为它自动继承当前 ScopedValue。 独立创建的线程与结构化并发作用域中的子任务不是同一种上下文传播语义。
5.1 独立虚拟线程的边界
import java.lang.ScopedValue;
public class VirtualThreadBoundary {
static final ScopedValue<String> ID = ScopedValue.newInstance();
public static void main(String[] args) throws Exception {
ScopedValue.where(ID, "parent").call(() -> {
Thread worker = Thread.ofVirtual().start(() ->
System.out.println("bound=" + ID.isBound()));
worker.join();
return null;
});
}
}
预期输出: bound=false。这是独立虚拟线程的示例,不应把它误认为由结构化并发管理的子任务。普通 Executor、消息消费者和 Reactor 链路也不能假定自动传播。
5.2 明确捕获并重新绑定
import java.lang.ScopedValue;
import java.util.concurrent.*;
public class ExplicitPropagation {
static final ScopedValue<String> ID = ScopedValue.newInstance();
public static void main(String[] args) {
try (ExecutorService executor =
Executors.newVirtualThreadPerTaskExecutor()) {
ScopedValue.where(ID, "req-99").run(() -> {
String captured = ID.get();
executor.submit(() ->
ScopedValue.where(ID, captured).run(() ->
System.out.println(ID.get())));
});
}
}
}
这里显式捕获不可变值并在任务内重新绑定。JDK 25 的 ExecutorService.close() 会按其契约等待任务终止,但业务仍需明确超时、取消、异常和资源释放。不要捕获完整 HTTP Request、可变 SecurityContext 或敏感凭据。
六、结构化并发的继承能力:仍需预览开关
Java 25 的 StructuredTaskScope 在打开作用域时捕获当前 ScopedValue 绑定,其管理的子任务可以继承这些绑定。下面使用 Java 25 预览 API:
import java.lang.ScopedValue;
import java.util.concurrent.StructuredTaskScope;
public class StructuredContext {
static final ScopedValue<String> REQUEST_ID =
ScopedValue.newInstance();
public static void main(String[] args) throws Exception {
ScopedValue.where(REQUEST_ID, "req-structured").call(() -> {
try (var scope = StructuredTaskScope.open()) {
var first = scope.fork(() -> REQUEST_ID.get() + "-A");
var second = scope.fork(() -> REQUEST_ID.get() + "-B");
scope.join();
System.out.println(first.get());
System.out.println(second.get());
}
return null;
});
}
}
javac –release 25 –enable-preview StructuredContext.java
java –enable-preview StructuredContext
预期输出
req-structured-A
req-structured-B
结构化并发子任务受作用域生命周期约束。它与随意启动线程后忘记等待不同,能够明确子任务完成、异常传播和取消边界。但它在 Java 25 仍是预览特性,不能把示例当作无需开关的生产默认方案。
七、Spring Boot 项目应该怎样迁移?
7.1 不要直接替换 Spring Security 上下文
SecurityContextHolder、事务同步、MDC、Reactor Context 都有独立的传播与生命周期规则。把所有 ThreadLocal 机械替换成 ScopedValue,可能破坏认证、事务、异步执行或日志关联。
较稳妥的迁移顺序:
7.2 Servlet Filter 的设计边界
同步 Servlet 请求可在过滤器中包住后续调用链:
ScopedValue.where(RequestContext.CURRENT, identity).run(() -> {
try {
chain.doFilter(request, response);
} catch (IOException | ServletException ex) {
throw new FilterFailure(ex);
}
});
其中 identity 必须来自已验证的认证上下文,FilterFailure 是自行实现的异常包装器。这只是绑定结构示意,不是完整可直接复制的 Filter。真实项目需要处理过滤器顺序、认证失败、异常映射、异步 Servlet 分派和跨线程调用。
八、用 JUnit 5 验证异常后自动恢复
import java.lang.ScopedValue;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
class ScopedValueTest {
static final ScopedValue<String> KEY = ScopedValue.newInstance();
@Test
void bindingMustDisappearAfterException() {
assertThrows(IllegalStateException.class, () ->
ScopedValue.where(KEY, "req").run(() -> {
assertEquals("req", KEY.get());
throw new IllegalStateException("boom");
}));
assertFalse(KEY.isBound());
}
@Test
void nestedBindingMustRestoreOuterValue() {
ScopedValue.where(KEY, "outer").run(() -> {
ScopedValue.where(KEY, "inner").run(() ->
assertEquals("inner", KEY.get()));
assertEquals("outer", KEY.get());
});
assertFalse(KEY.isBound());
}
}
这些是可复现的预期断言,尚未在本次写作环境执行。测试 ScopedValue 正式 API 无需预览开关;测试 StructuredTaskScope 时需要单独配置。
| 同步调用 | 内层方法读取当前绑定 |
| 嵌套作用域 | 内层退出后恢复外层 |
| 作用域内抛异常 | 退出后不残留绑定 |
| 独立虚拟线程 | 不假设自动继承 |
| 结构化子任务 | 绑定继承与作用域关闭 |
| @Async / Reactor | 明确传播策略,避免串租户 |
九、性能与安全:不要过度承诺
JEP 506 讨论了更清晰的生命周期以及大量线程场景下的设计优势,但不能据此声称你的 Spring Boot 服务吞吐量一定提升多少百分比。真实性能取决于调用深度、虚拟线程数量、JIT、上下文大小和业务 I/O。
ScopedValue 不是权限系统:绑定值来自可信入口,访问敏感资源时仍应检查用户权限、租户归属和数据范围。绑定的对象如果是可变的,跨线程时仍需同步;如果包含密钥,也存在日志与异常泄露风险。
什么时候继续使用 ThreadLocal? 需要线程局部可变状态、依赖已有框架机制,或者项目必须兼容 Java 17。
什么时候考虑 ScopedValue? JDK 25 环境中,明确的同步调用范围需要传递只读上下文,或计划配合结构化并发管理子任务上下文时。
十、结论
ScopedValue 的价值不是“替换所有 ThreadLocal”,而是让上下文绑定与调用生命周期一致。Java 25 已正式支持,但独立虚拟线程不等于自动继承、结构化并发仍为预览,Spring Security 和 Reactor 也有各自的传播机制。迁移应从少量只读业务上下文开始,用异常恢复和异步边界测试证明正确性。
官方参考
- JEP 506:Scoped Values
- Oracle Java 25 Scoped Values
- Oracle Java 25 Structured Concurrency(Preview)
- Java SE 25 ScopedValue API
网硕互联帮助中心


评论前必须登录!
注册