在 Java 生态中，上下文传递一直是开发中的痛点，尤其是在引入虚拟线程后，传统的 ThreadLocal 方案逐渐暴露出性能与安全性的短板。本文将聚焦两个高频业务场景——虚拟线程中的用户上下文传递和多模块间的无参数据传递，通过完整的代码实现和流程分析，带你掌握 ScopedValue 的基础用法，真正把技术转化为生产力。

场景一：虚拟线程中传递用户上下文

需求描述

在基于 Spring Boot 的 Web 项目中，使用虚拟线程处理 HTTP 请求，需要在请求处理链路中传递用户 ID 和 Token 信息，要求：

  • 无需通过方法参数传递，服务层、数据层可直接获取
  • 保证不同请求之间的数据隔离，无脏数据风险
  • 适配虚拟线程，无内存泄漏问题

解题思路

核心思想：利用 ScopedValue 的作用域绑定 + 不可变设计特性，在虚拟线程处理请求的入口处绑定用户上下文数据，通过 runWhere() 限定作用域，使整个请求链路内的方法都能直接获取数据，请求结束后自动清理绑定关系。

与传统的 ThreadLocal 相比，ScopedValue 在虚拟线程环境下的优势尤为明显。ThreadLocal 依赖于线程的身份标识（即线程哈希表），而虚拟线程数量庞大且频繁挂起恢复，会导致哈希表性能损耗和内存泄漏风险。ScopedValue 采用栈存储方式，直接绑定在作用域上，而不是线程上，因此更适合虚拟线程的轻量级特性。类似地，在 C++ 和 Go 语言中也有作用域绑定的概念（如 C++ 的 thread_local 与 Go 的 context），但 ScopedValue 在 Java 中的实现更为简洁和安全。

核心逻辑：

  • 定义 UserContext 类封装用户 ID 和 Token 信息
  • 定义 ScopedValue 实例存储 UserContext 对象
  • 在请求拦截器中解析请求头中的用户信息，通过 ScopedValue.runWhere() 绑定到当前虚拟线程
  • 服务层、数据层直接通过 ScopedValue 获取上下文数据
  • 请求处理完毕后，作用域自动销毁，数据绑定关系解除

代码实现

1. 定义上下文载体类

首先，创建一个不可变的 UserContext 类，用于封装用户 ID 和 Token。注意，类应设计为不可变（无 setter 方法），确保数据不会被业务层篡改。

/**
 * 用户上下文载体类
 */
public class UserContext {
    private final String userId;
    private final String token;
    public UserContext(String userId, String token) {
        this.userId = userId;
        this.token = token;
    }
    // 提供getter方法，无setter保证不可变性
    public String getUserId() {
        return userId;
    }
    public String getToken() {
        return token;
    }
}

2. 定义 ScopedValue 全局实例

然后，在全局范围内声明一个 ScopedValue<UserContext> 实例，作为上下文的持有者。

/**
 * 上下文持有工具类
 */
public class ScopedValueContextHolder {
    // 定义ScopedValue实例，存储UserContext
    public static final ScopedValue USER_CONTEXT = ScopedValue.newInstance();
    // 私有化构造方法，禁止实例化
    private ScopedValueContextHolder() {}
    // 封装获取方法，简化业务层调用
    public static UserContext getCurrentUser() {
        return USER_CONTEXT.get();
    }
}

3. 编写请求拦截器绑定上下文

在 Spring Boot 的拦截器中，从 HTTP 请求头中提取用户信息，并通过 runWhere() 绑定到当前虚拟线程的作用域中。

/**
 * 请求拦截器：解析用户信息并绑定到ScopedValue
 */
@Component
public class UserContextInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 从请求头解析用户信息（实际业务中需结合认证逻辑）
        String userId = request.getHeader("X-User-Id");
        String token = request.getHeader("X-Token");
        if (userId == null || token == null) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            return false;
        }
        UserContext userContext = new UserContext(userId, token);
        // 绑定上下文到ScopedValue，并继续执行请求
        // 注意：此处需通过Callable包装后续请求处理逻辑，保证作用域生效
        request.setAttribute("scopedTask", (Callable) () -> {
            try {
                return ((HandlerMethod) handler).getMethod().invoke(((HandlerMethod) handler).getBean(), request, response);
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        });
        ScopedValue.runWhere(ScopedValueContextHolder.USER_CONTEXT, userContext, () -> {
            try {
                ((Callable) request.getAttribute("scopedTask")).call();
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        });
        return false;
    }
}


4. 业务层和数据层使用上下文
在服务层或数据层中，直接通过 ScopedValue.get() 获取用户上下文，无需通过方法参数传递。


/**
 * 服务层示例
 */
@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    public UserVO getUserInfo() {
        // 直接从ScopedValue获取上下文，无需方法参数传递
        UserContext userContext = ScopedValueContextHolder.getCurrentUser();
        // 调用数据层方法
        UserDO userDO = userMapper.selectById(userContext.getUserId());
        return convertToVO(userDO);
    }
    private UserVO convertToVO(UserDO userDO) {
        // 省略对象转换逻辑
        return new UserVO();
    }
}


/**
 * 数据层示例（MyBatis Mapper）
 */
@Mapper
public interface UserMapper {
    @Select("select id, username, email from t_user where id = #{userId}")
    UserDO selectById(String userId);
}



5. 配置虚拟线程和拦截器
最后，在 Spring Boot 配置中启用虚拟线程，并注册自定义拦截器。


/**
 * Web配置类
 */
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private UserContextInterceptor userContextInterceptor;
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(userContextInterceptor).addPathPatterns("/**");
    }
    // 配置虚拟线程执行器
    @Bean
    public TaskExecutor virtualThreadTaskExecutor() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }
    // 配置Spring MVC使用虚拟线程处理请求
    @Bean
    public WebMvcConfigurer webMvcConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
                configurer.setTaskExecutor(virtualThreadTaskExecutor());
            }
        };
    }
}



运行结果与分析
  • 数据隔离性：不同请求的用户上下文数据完全隔离，即使虚拟线程复用，也不会出现脏数据，因为每个请求的作用域都是独立的。
  • 内存安全性：请求处理完毕后，runWhere() 绑定的作用域自动销毁，UserContext 数据随之解除绑定，无内存泄漏风险。
  • 性能优势：在高并发场景下，ScopedValue 的栈存储方式比 ThreadLocal 的哈希表查找更高效，能充分发挥虚拟线程的轻量级优势。
⚠️ 注意事项：必须在 runWhere() 方法的作用域内调用 get()，否则会抛出 IllegalStateException。UserContext 类需设计为不可变（无 setter 方法），确保数据不会被业务层篡改。


[AFFILIATE_SLOT_1]


场景二：多模块间的无参数据传递
需求描述
在一个订单处理系统中，订单创建流程涉及订单服务、库存服务、日志服务三个模块，需要传递订单 ID 用于全链路日志追踪，要求：
  • 模块间调用时无需传递订单 ID 参数
  • 日志服务能自动获取当前订单 ID，打印全链路日志
  • 保证不同订单处理线程的数据隔离
解题思路
 核心思想：利用 ScopedValue 的跨方法无参传递特性，在订单创建的入口处绑定订单 ID，使下游的库存服务、日志服务能直接获取该值，简化模块间的参数传递逻辑。
在传统的架构中，为了实现全链路追踪，通常需要将订单 ID 作为参数逐层传递，导致代码冗余且耦合度高。而在 JavaScript 或 TypeScript 的异步编程中，开发者常使用闭包或上下文对象来传递数据，但这种方式在 Java 的同步/异步混合场景中并不优雅。ScopedValue 提供了一种声明式的解决方案，类似于 Go 语言中的 context.Context，但更轻量且线程安全。
核心逻辑：
  • 定义 ScopedValue 实例存储订单 ID
  • 订单服务在创建订单时，通过 runWhere() 绑定订单 ID
  • 库存服务扣减库存时，直接获取订单 ID
  • 日志服务打印日志时，自动附加订单 ID
  • 订单流程结束后，作用域自动销毁
代码实现
1. 扩展上下文持有工具类
为了统一管理多个 ScopedValue 实例，可以创建一个工具类，例如 ScopedValueContextHolder，其中包含订单 ID 的 ScopedValue 声明。


/**
 * 上下文持有工具类（扩展订单ID）
 */
public class ScopedValueContextHolder {
    public static final ScopedValue USER_CONTEXT = ScopedValue.newInstance();
    // 新增订单ID的ScopedValue实例
    public static final ScopedValue ORDER_ID = ScopedValue.newInstance();
    private ScopedValueContextHolder() {}
    public static UserContext getCurrentUser() {
        return USER_CONTEXT.get();
    }
    // 封装订单ID的获取方法
    public static String getCurrentOrderId() {
        return ORDER_ID.get();
    }
}



2. 订单服务绑定订单 ID
在订单服务中，创建订单后立即绑定订单 ID，并调用下游模块。


/**
 * 订单服务
 */
@Service
public class OrderService {
    @Autowired
    private StockService stockService;
    @Autowired
    private LogService logService;
    public void createOrder(OrderCreateDTO orderCreateDTO) {
        // 生成订单ID（实际业务中可使用雪花算法）
        String orderId = "ORDER_" + System.currentTimeMillis();
        // 绑定订单ID到ScopedValue，限定作用域
        ScopedValue.runWhere(ScopedValueContextHolder.ORDER_ID, orderId, () -> {
            // 调用库存服务扣减库存
            stockService.deductStock(orderCreateDTO.getProductId(), orderCreateDTO.getQuantity());
            // 记录订单创建日志
            logService.info("订单创建成功");
            // 后续业务逻辑...
        });
    }
}



3. 库存服务和日志服务使用订单 ID
库存服务和日志服务无需接收订单 ID 参数，直接通过 ScopedValueContextHolder 获取。


/**
 * 库存服务
 */
@Service
public class StockService {
    @Autowired
    private LogService logService;
    public void deductStock(String productId, Integer quantity) {
        // 获取当前订单ID
        String orderId = ScopedValueContextHolder.getCurrentOrderId();
        logService.info("订单[" + orderId + "]开始扣减商品[" + productId + "]库存");
        // 库存扣减逻辑...
    }
}


/**
 * 日志服务
 */
@Service
public class LogService {
    private static final Logger logger = LoggerFactory.getLogger(LogService.class);
    public void info(String message) {
        try {
            // 获取当前订单ID，若未绑定则为空
            String orderId = ScopedValueContextHolder.getCurrentOrderId();
            logger.info("[订单ID: {}] {}", orderId, message);
        } catch (IllegalStateException e) {
            logger.info("[订单ID: 未知] {}", message);
        }
    }
}



4. 测试代码
编写测试代码验证多线程并发场景下的数据隔离性。


/**
 * 测试类
 */
@SpringBootTest
public class OrderServiceTest {
    @Autowired
    private OrderService orderService;
    @Test
    public void testCreateOrder() {
        OrderCreateDTO dto = new OrderCreateDTO();
        dto.setProductId("PROD_001");
        dto.setQuantity(2);
        // 执行订单创建
        orderService.createOrder(dto);
    }
}



运行结果与分析
✅ 日志输出示例：


[订单ID: ORDER_1718000000000] 订单[ORDER_1718000000000]开始扣减商品[PROD_001]库存
[订单ID: ORDER_1718000000000] 订单创建成功


  • 参数简化：库存服务和日志服务无需接收订单 ID 参数，直接通过 ScopedValueContextHolder 获取，降低了模块间的耦合度。
  • 链路追踪：日志中自动附加订单 ID，方便排查问题时追溯全链路流程。
  • 作用域隔离：多个订单并发处理时，各自的订单 ID 互不干扰，数据隔离性得到保证。
⚠️ 注意事项：嵌套作用域下，内层 ScopedValue 会覆盖外层同名实例的值，外层值在嵌套作用域结束后恢复。若作用域外调用 getCurrentOrderId()，会抛出异常，需在日志服务中捕获并处理。
常见问题与解决方案
在实际使用 ScopedValue 时，可能会遇到以下问题，我们整理了对应的解决方案：
常见问题
解决方案
作用域外调用 get() 抛出 IllegalStateException
1. 确保所有获取操作都在 runWhere() 作用域内；2. 工具类中捕获异常，返回默认值或空
嵌套作用域数据覆盖
利用 ScopedValue 的栈式存储特性，内层作用域使用完毕后自动恢复外层值，无需手动处理
无法动态修改数据
ScopedValue 不可变，若需更新数据，可通过嵌套 runWhere() 绑定新值


[AFFILIATE_SLOT_2]


小结
通过两个基础实战场景的学习，我们可以发现 ScopedValue 在上下文传递场景中的核心价值：简化参数传递、保证数据安全、适配虚拟线程。它不是 ThreadLocal 的“替代品”，而是在特定场景下的“优化方案”。无论是 Java 开发者，还是熟悉 C++、Go 或 TypeScript 的工程师，都可以从 ScopedValue 的设计中借鉴作用域绑定的思想，提升代码的健壮性和可维护性。
在下一篇实战文章中，我们将探索 ScopedValue 的高级用法，结合 Stream API 和 CompletableFuture 实现异步场景下的上下文传递，敬请期待。