架构与系统设计 / 系统课时
租户上下文组件
租户上下文组件
本课将把已识别的租户信息封装成可控的线程上下文,使业务代码能够统一读取租户编号、来源、用户和追踪信息,同时避免线程池复用导致的租户数据串用。
学习目标
- 设计不可变的租户上下文数据结构
- 使用
ThreadLocal安全地绑定和清理上下文 - 识别异步执行与线程切换带来的传播边界
上下文应保存什么
租户上下文只保存当前请求链路必须共享的元数据,不承载订单、商户详情等业务对象。推荐字段包括租户编号、识别来源、当前用户编号和追踪编号。数据对象应保持不可变,避免某个业务方法在链路中途修改租户身份。
上下文组件通常提供三个能力:绑定当前上下文、读取当前上下文、在请求结束时清理。清理不是可选步骤,因为 Servlet 容器和线程池会复用工作线程;若旧值残留,下一个请求可能读取到前一个租户的信息。
请求生命周期
租户上下文应在认证与租户识别完成后创建,在进入控制器前绑定,并在整个请求结束后无条件清理。即使业务抛出异常,清理逻辑也必须执行。

最可靠的调用方式是让绑定操作返回一个可关闭作用域,并通过 try-with-resources 自动清理。这样调用方不容易遗漏 finally,也能阻止同一线程重复绑定不同租户。
主示例:实现安全的 ThreadLocal 上下文
下面示例可直接使用 JDK 17 编译运行。TenantScope 负责在作用域结束时清理,bind 则禁止未清理情况下再次绑定。
public final class TenantContextDemo {
private static final ThreadLocal<TenantInfo> HOLDER = new ThreadLocal<>();
public static void main(String[] args) {
TenantInfo info = new TenantInfo(
"tenant-1001",
"verifiedToken",
"user-88",
"trace-abc");
try (TenantScope ignored = bind(info)) {
TenantInfo current = requireCurrent();
System.out.println("tenant=" + current.tenantId());
System.out.println("user=" + current.userId());
System.out.println("trace=" + current.traceId());
}
System.out.println("cleared=" + (currentOrNull() == null));
}
public static TenantScope bind(TenantInfo info) {
if (info == null) {
throw new IllegalArgumentException("TenantInfo must not be null");
}
if (HOLDER.get() != null) {
throw new IllegalStateException("Tenant context already bound");
}
HOLDER.set(info);
return new TenantScope();
}
public static TenantInfo requireCurrent() {
TenantInfo info = HOLDER.get();
if (info == null) {
throw new IllegalStateException("Tenant context is missing");
}
return info;
}
public static TenantInfo currentOrNull() {
return HOLDER.get();
}
public record TenantInfo(
String tenantId,
String source,
String userId,
String traceId) {
}
public static final class TenantScope implements AutoCloseable {
private boolean closed;
@Override
public void close() {
if (!closed) {
HOLDER.remove();
closed = true;
}
}
}
}预期输出:
tenant=tenant-1001
user=user-88
trace=trace-abc
cleared=true这里使用 remove() 而不是 set(null),目的是让当前线程彻底移除对应条目。requireCurrent() 适合必须存在租户的业务路径;公开健康检查、登录入口等无租户接口则可使用 currentOrNull(),但必须明确白名单,不能在普通业务中悄悄降级为空租户。
接入 Web 请求链路
在 Spring Boot 项目中,通常由过滤器完成绑定与清理。处理顺序应是:生成或读取追踪号、完成身份认证、识别并授权租户、绑定上下文、继续过滤器链、最终清理。若清理代码没有位于 finally 或自动关闭作用域中,异常请求就可能泄漏上下文。
片段示例,以下代码依赖前面的 TenantInfo、bind 和项目中的 resolveTenantInfo 方法:
TenantInfo info = resolveTenantInfo(request);
try (TenantScope ignored = TenantContextDemo.bind(info)) {
filterChain.doFilter(request, response);
}生效行为是:控制器与服务层在同一请求线程中都能读取相同上下文,请求结束后线程内不再保留租户数据。验证时可连续发送两个不同租户的请求,并在服务入口与出口打印租户编号和线程名,确认没有交叉。
异步与响应式边界
普通 ThreadLocal 只对当前线程可见。提交到线程池、使用 CompletableFuture、消息队列消费者或响应式链路时,执行线程可能变化,不能假设上下文自动传播。正确做法是显式捕获不可变的 TenantInfo,在异步任务开始时重新绑定,并在任务结束时清理。
不要直接使用 InheritableThreadLocal 解决线程池传播问题。线程池线程通常早已创建,继承时机与任务提交时机不同,而且旧值更容易残留。响应式项目应使用 Reactor Context;跨服务调用则应把租户编号放入经过签名或受信链路保护的请求元数据,并由下游重新校验。
本课总结
- 租户上下文应保存少量不可变元数据,并提供绑定、读取和清理能力
ThreadLocal必须在请求结束时执行remove(),异常路径也不能遗漏- 线程切换和跨服务调用必须显式传播并重新校验上下文
下一课预告
下一课将把租户上下文接入网关、过滤器和内部调用链,确保租户信息能够安全地贯穿完整请求链路。