架构与系统设计 / 系统课时
上下文传播与清理
上下文传播与清理
本课解决租户上下文离开请求线程后的安全问题:异步任务提交时复制当前租户,在线程池线程执行前恢复,执行结束后还原或清理,从而同时避免上下文丢失、线程复用串租和嵌套任务覆盖。
学习目标
- 理解普通
ThreadLocal在线程池中的失效原因 - 使用
TaskDecorator完成租户上下文快照、恢复与清理 - 建立请求结束、异步结束和嵌套调用的统一清理规则
为什么异步任务会丢失租户
ThreadLocal 的值绑定在线程上,而不是绑定在请求或任务上。请求线程把任务提交到线程池后,真正执行代码的可能是另一条线程,因此它默认看不到请求线程中的租户编号。
更危险的是线程池线程会被反复复用。如果一次任务写入租户后没有清理,下一次由同一线程执行的任务可能读到上一个租户,形成隐蔽的跨租户数据访问。

采用快照而不是共享对象
传播时只复制不可变的租户编号,不要把整个请求对象、认证对象或可变 Map 直接交给异步线程。提交任务的瞬间生成快照,可以保证任务执行时使用的是确定值。
还原逻辑要区分两种情况:工作线程原来没有租户时,执行后调用 clear();工作线程原来已有租户时,执行后恢复旧值。后一种处理能兼容嵌套任务和测试场景。
配置 TaskDecorator
下面示例适用于 Spring Boot 的 ThreadPoolTaskExecutor。TenantTaskDecorator 在提交阶段捕获租户,在执行阶段设置上下文,并在 finally 中恢复现场。
import java.util.concurrent.Executor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskDecorator;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
final class TenantTaskDecorator implements TaskDecorator {
@Override
public Runnable decorate(Runnable task) {
String capturedTenantId = TenantContext.getTenantId();
return () -> {
String previousTenantId = TenantContext.getTenantId();
try {
// 在工作线程执行前恢复提交任务时的租户快照
if (capturedTenantId == null) {
TenantContext.clear();
} else {
TenantContext.setTenantId(capturedTenantId);
}
task.run();
} finally {
// 恢复工作线程原有现场,避免线程复用造成串租
if (previousTenantId == null) {
TenantContext.clear();
} else {
TenantContext.setTenantId(previousTenantId);
}
}
};
}
}
@Configuration
@EnableAsync
public class AsyncExecutorConfig {
@Bean("tenantExecutor")
public Executor tenantExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(4);
executor.setMaxPoolSize(8);
executor.setQueueCapacity(200);
executor.setThreadNamePrefix("tenant-async-");
executor.setTaskDecorator(new TenantTaskDecorator());
executor.initialize();
return executor;
}
}配置生效后,使用 @Async("tenantExecutor") 的任务会自动携带提交时的租户。没有经过该执行器的手工线程、其他线程池和消息消费者仍需单独处理。
在异步服务中验证
下面是片段示例,依赖前面的 tenantExecutor。异步方法只读取上下文,不需要自行设置租户;传播和清理由执行器统一完成。
import java.util.concurrent.CompletableFuture;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
@Service
public class TenantAsyncService {
@Async("tenantExecutor")
public CompletableFuture<String> currentTenant() {
String tenantId = TenantContext.getTenantId();
return CompletableFuture.completedFuture(
Thread.currentThread().getName() + ":" + tenantId);
}
}可通过一个测试接口在请求线程提交任务。
curl -s -H "X-Tenant-Id: tenant-a" http://localhost:<PORT>/api/async/current-tenant预期输出中的线程序号可能不同,但租户编号应保持为 tenant-a。
tenant-async-<ID>:tenant-a连续使用 tenant-a、tenant-b 发起请求时,每次结果都应与本次请求一致,且在线程池空闲后检查上下文应为 null。
其他异步边界怎么处理
消息队列消费者没有原始 HTTP 请求线程,租户编号必须放入消息头或消息体,并在消费开始时校验、写入上下文,在消费结束的 finally 中清理。定时任务则应显式遍历目标租户,每处理一个租户都建立独立作用域。
CompletableFuture.supplyAsync() 默认使用公共线程池,不会自动套用 Spring 的 TaskDecorator。应传入 tenantExecutor,或者封装统一的异步提交组件,禁止业务代码随意选择执行器。
清理规则与验收
请求过滤器负责清理请求线程,TaskDecorator 负责清理线程池工作线程,消息监听器负责清理消费线程。谁写入,谁就必须在同一作用域的 finally 中恢复或清理。
验收时至少覆盖三项:不同租户连续提交到同一线程池不串租;异步任务抛异常后上下文仍被清理;无租户任务不会继承线程池残留值。
本课总结
- 普通
ThreadLocal不会自动跨线程传播,线程池复用还会放大残留风险 TaskDecorator应在提交时捕获快照,在执行前设置,并在finally中恢复现场- HTTP、异步任务、消息消费和定时任务都必须遵守“谁写入,谁清理”
下一课预告
下一课将继续完善租户链路,把租户编号安全地传递到内部 HTTP 调用和消息事件中,形成跨服务的一致上下文。