3、租户上下文设计：ThreadLocal与InheritableThreadLocal原理、租户上下文传递模式

在多租户SaaS架构中，鉴权拦截链路的核心挑战是：如何在一次请求的整个处理生命周期内，准确、高效地传递当前租户的身份标识。租户上下文（Tenant Context）的设计直接决定了鉴权逻辑的可维护性、线程安全性和异步链路追踪能力。

3.1 ThreadLocal 原理与租户上下文绑定

ThreadLocal 是 Java 中实现线程局部变量的核心机制。每个线程拥有自己独立的变量副本，线程之间互不干扰。在同步请求处理模型（如 Tomcat 的线程池 + Servlet 同步处理）中，ThreadLocal 是存储租户上下文的理想选择。

核心原理：每个 Thread 对象内部维护一个 ThreadLocalMap，以 ThreadLocal 实例为 key，以租户上下文对象为 value。线程内任意位置均可通过 ThreadLocal.get() 获取当前租户信息，无需显式传递参数。

3.1.1 ThreadLocal 租户上下文实现

public class TenantContext {
    private static final ThreadLocal<TenantInfo> CONTEXT = new ThreadLocal<>();

    public static void setTenant(TenantInfo tenant) {
        CONTEXT.set(tenant);
    }

    public static TenantInfo getTenant() {
        return CONTEXT.get();
    }

    public static void clear() {
        CONTEXT.remove();
    }
}

// 在鉴权过滤器中设置
public class TenantAuthFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
        try {
            String tenantId = extractTenantFromRequest(request);
            TenantInfo tenant = authenticateTenant(tenantId);
            TenantContext.setTenant(tenant);
            chain.doFilter(request, response);
        } finally {
            TenantContext.clear(); // 防止内存泄漏
        }
    }
}
⚠️ 关键陷阱：必须在 finally 块中调用 clear() 方法。Tomcat 等 Servlet 容器使用线程池，线程会被复用。若不清理，下一个请求可能误用上一个请求的租户上下文，导致严重的数据泄露事故。

3.2 InheritableThreadLocal 原理与异步传递

当业务链路中出现异步处理（如 CompletableFuture、@Async 注解、手动创建子线程）时，ThreadLocal 无法将租户上下文传递给子线程。InheritableThreadLocal 解决了父线程向子线程传递上下文的问题。

特性 ThreadLocal InheritableThreadLocal
作用范围 当前线程 当前线程 + 子线程
传递时机 无传递 子线程创建时复制父线程的值
线程池场景 不适用 仅首次创建时传递，复用线程不更新
内存泄漏风险 需手动 remove 需手动 remove，且子线程需额外清理
适用场景 同步请求处理 简单异步任务（非线程池）

3.2.1 InheritableThreadLocal 实现示例

public class TenantContext {
    private static final InheritableThreadLocal<TenantInfo> CONTEXT = new InheritableThreadLocal<>() {
        @Override
        protected TenantInfo childValue(TenantInfo parentValue) {
            // 深拷贝防止子线程修改影响父线程
            return parentValue != null ? new TenantInfo(parentValue) : null;
        }
    };

    public static void setTenant(TenantInfo tenant) {
        CONTEXT.set(tenant);
    }

    public static TenantInfo getTenant() {
        return CONTEXT.get();
    }

    public static void clear() {
        CONTEXT.remove();
    }
}
💡 深拷贝建议：重写 childValue() 方法时，务必进行深拷贝。若直接返回 parentValue 引用，子线程修改租户对象属性将污染父线程上下文，引发难以排查的并发问题。

3.3 租户上下文传递模式对比

在实际SaaS系统中，根据异步实现方式的不同，需要选择不同的上下文传递模式。以下是三种主流模式的对比：

传递模式 实现方式 线程池支持 性能开销 推荐场景
InheritableThreadLocal JVM原生支持，子线程创建时复制 ❌ 不支持（仅首次创建） 低 简单异步、非线程池场景
TransmittableThreadLocal 阿里TTL框架，包装线程池 ✅ 完整支持 中 线程池 + 异步任务
显式参数传递 方法参数传递租户ID ✅ 完全支持 高（代码侵入性强） 函数式编程、响应式流

3.4 租户上下文传递架构图

下图展示了在典型SaaS请求链路中，租户上下文从HTTP请求进入，经过鉴权拦截器，通过ThreadLocal/InheritableThreadLocal在不同组件间传递的完整流程：

租户上下文传递架构图 HTTP 请求 鉴权拦截器 (Filter/Interceptor) 提取租户ID → 认证 → TenantContext.setTenant() ThreadLocal / InheritableThreadLocal 存储 TenantInfo (tenantId, tenantName, tier) 同步业务链路 Service → DAO → 数据库（同线程） 异步业务链路 CompletableFuture / @Async / 线程池 ThreadLocal.get() 直接获取 InheritableThreadLocal / TTL 传递 finally: TenantContext.clear() 防止泄漏

3.5 线程池场景下的上下文传递挑战

InheritableThreadLocal 在普通子线程创建时工作良好，但在线程池场景下存在致命缺陷：线程池中的线程被复用，子线程仅在首次创建时复制父线程上下文，后续任务不会更新上下文。

解决方案：使用阿里开源的 TransmittableThreadLocal (TTL) 框架。TTL 通过包装 ThreadPoolExecutor，在每次提交任务时捕获当前线程的上下文快照，并在任务执行前恢复上下文，执行后清理。

3.5.1 TTL 使用示例

// 1. 定义 TransmittableThreadLocal
TransmittableThreadLocal<TenantInfo> context = new TransmittableThreadLocal<>();

// 2. 包装线程池（推荐方式）
ExecutorService executor = TtlExecutors.getTtlExecutorService(
    new ThreadPoolExecutor(4, 8, 60, TimeUnit.SECONDS, new LinkedBlockingQueue<>())
);

// 3. 提交任务时自动传递上下文
executor.submit(() -> {
    TenantInfo tenant = context.get(); // 自动获取父线程的租户上下文
    processTenantData(tenant);
});

3.6 租户上下文传递模式决策树

在实际项目中，应根据异步实现方式选择正确的传递模式：

  1. 纯同步链路（无异步操作）：使用 ThreadLocal，简单高效。
  2. 简单异步（手动创建子线程，非线程池）：使用 InheritableThreadLocal，注意深拷贝。
  3. 线程池异步（@Async、CompletableFuture、自定义线程池）：使用 TransmittableThreadLocal + TtlExecutors。
  4. 响应式/协程（WebFlux、Kotlin Coroutines）：使用 Context 或 ReactorContext 显式传递。
💡 最佳实践：在微服务架构中，建议将租户上下文传递与链路追踪（TraceId）统一管理。使用同一套 TransmittableThreadLocal 机制，同时传递租户信息和追踪上下文，避免维护两套传递逻辑。

3.7 租户上下文传递模式对比图

下图从线程模型和传递机制两个维度，对比三种上下文传递模式在请求链路中的行为差异：

三种上下文传递模式对比 模式1：ThreadLocal（同步） 主线程（Tomcat线程） Service A（同线程） Service B（同线程） DAO（同线程） ✅ 同线程，直接 get() 模式2：InheritableThreadLocal 主线程（父线程） 子线程1（创建时复制） 子线程2（创建时复制） ⚠️ 仅首次创建时复制 线程池复用时不更新 模式3：TransmittableThreadLocal 主线程（父线程） 线程池任务1（快照传递） 线程池任务2（快照传递） 任务执行后自动清理 ✅ 每次提交任务时快照传递 线程池复用场景完美支持 关键结论 1. ThreadLocal：适用于纯同步链路，同线程内直接获取，性能最优。 2. InheritableThreadLocal：适用于手动创建子线程（非线程池），注意深拷贝和内存泄漏。 3. TransmittableThreadLocal：适用于线程池场景，是生产环境的最佳选择。 4. 统一原则：在微服务架构中，建议将租户上下文与链路追踪上下文合并管理，使用同一套传递机制。

3.8 生产环境注意事项

  • 内存泄漏防护：无论使用哪种 ThreadLocal 变体，都必须在请求结束或任务完成时调用 remove() 清理上下文。
  • 深拷贝策略：在 childValue() 或 TTL 快照中，对可变对象进行深拷贝，防止子线程修改影响父线程。
  • 统一管理：将租户上下文与 TraceId、SpanId 等链路追踪信息封装在同一个上下文对象中，使用同一套传递机制。
  • 测试覆盖：编写异步链路测试用例，验证上下文在 @Async、CompletableFuture、线程池等场景下的正确传递。
← 上一章 📖 返回目录 下一章 →