Java ScopedValue 和 ThreadLocal 在任务边界上有什么区别

Java 25 里，ScopedValue 和 ThreadLocal 都能让调用链中的方法读取“不放在参数里”的上下文，但它们解决的不是同一个边界问题：如果值由上游绑定、下游只读，并且应该随着一次调用结束而失效，优先用 ScopedValue；如果值需要在同一线程内被反复修改，或旧框架已经依赖线程本地状态，可以继续用 ThreadLocal，但必须把 remove() 放到任务收口处。

先看任务边界：只读上下文还是可变线程状态

不要先问“哪个性能更好”，先问三个问题：谁负责写入、值在什么时候失效、下游是否应该修改它。请求追踪号、租户标识、只读安全上下文通常由入口一次绑定，后面的服务和仓储只读取；这正是 ScopedValue 的形状。可复用的格式化器、线程绑定的临时缓存，或必须由同一线程逐步更新的状态，才更接近 ThreadLocal。

ScopedValue 的最小写法：绑定、读取、自动解除

ScopedValue 的关键不是“每个线程一份”，而是 where(key, value) 把一次操作放进动态作用域。调用链里的代码只要持有同一个 key，就能读取当前值；run 或 call 返回后，绑定自动解除。

private static final ScopedValue REQUEST = ScopedValue.newInstance();

static String handle(String traceId) throws Exception {
    var context = new RequestContext(traceId);
    // 入口只绑定一次；下游方法只能读取这个不可变上下文。
    return ScopedValue.where(REQUEST, context).call(() -> loadOrder());
}

static String loadOrder() {
    // 未绑定时主动失败，避免把缺失上下文误当成空字符串。
    return REQUEST.orElseThrow(() -> new IllegalStateException("missing request context"))
                  .traceId();
}

需要临时覆盖时可以嵌套 where，内层读取到新值，内层结束后回到外层值。这种“进入时绑定、退出时恢复”的语义很适合请求上下文，也减少了忘记清理的机会。共享给子线程时，值本身应保持不可变，或由调用方提供同步保护。

ThreadLocal 为什么必须在任务边界清理

ThreadLocal 的生命周期默认是线程级：线程池中的工作线程执行完任务 A 后仍然存活，槽位里的值也可能继续存在。任务 B 恰好复用该线程时，读取到的就可能是 A 的用户或 traceId。这个问题不是把线程池调大就能解决的。

private static final ThreadLocal TRACE_ID = new ThreadLocal();

static void handle(String traceId) {
    TRACE_ID.set(traceId);
    try {
        // 业务调用链可通过 TRACE_ID.get() 读取当前任务的值。
        processOrder();
    } finally {
        // 在线程池复用前清空槽位，避免下一个任务继承旧上下文。
        TRACE_ID.remove();
    }
}

如果确实要保留 ThreadLocal，把 set 和 remove 视为一对操作。尤其不要只在“正常返回”分支清理，因为异常、取消和超时同样会离开任务。

嵌套绑定、子任务和执行器边界怎么选

ScopedValue 可以表达嵌套动态作用域；配合 Java 25 的 StructuredTaskScope 时，绑定可以被结构化子任务继承，前提是共享数据不可变或有同步措施。它不是任意异步 API 的魔法传播器：把任务丢进不受当前结构管理的执行器、消息队列或回调系统时，仍要明确传递上下文。

实际迁移可以按这个顺序判断：先把只读上下文改成不可变对象；再把入口绑定改成 ScopedValue.where(...).run/call；最后检查所有异步分叉是否属于结构化作用域。若下游必须改变值，或库的契约就是通过 ThreadLocal 读取，就先保留 ThreadLocal，并补齐 try/finally 清理。

常见问题

ScopedValue 能完全替代 ThreadLocal 吗？

不能。它更适合单向、只读、边界明确的上下文；可变线程状态和依赖旧 ThreadLocal 契约的库仍需要 ThreadLocal 或显式参数。

ThreadLocal 只要在线程结束时清理就够了吗？

在线程池里不够，因为工作线程通常会继续执行其他任务。应在每个任务的 finally 中调用 remove()。

ScopedValue 的值可以是可变对象吗？

API 允许绑定对象，但跨线程共享时不要把它当成同步工具。更稳妥的做法是绑定不可变 record，或为共享对象建立明确的同步策略。

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