ThreadLocal 是线程级上下文容器的基础设施，需配合租户识别机制实现多租户隔离；租户ID应在请求入口（如Filter）中提取并存入，请求结束时必须remove()；推荐封装为TenantContextHolder并与Spring RequestContext集成；数据库隔离需联动MyBatis拦截器或Hibernate多租户方案；异步场景需TaskDecorator传递上下文，WebFlux应避免使用ThreadLocal。
ThreadLocal 本身不直接实现多租户隔离，而是作为**线程级上下文容器的基础设施**，配合租户识别机制（如请求头、子域名、Token 声明等），才能完成多租户上下文参数的隔离。关键在于：谁往 ThreadLocal 里放值、何时放、放什么，以及如何确保每次请求都绑定正确的租户标识。
租户标识的提取与绑定
在 Web 请求入口（如 Spring 的 Filter 或 WebMvc 的 HandlerInterceptor）中，从当前请求中解析出租户 ID（例如 X-Tenant-ID 头、JWT 中的 tenant 字段、或 URL 路径前缀），然后存入 ThreadLocal：
- 定义一个静态 ThreadLocal<String>： private static final ThreadLocal<String> CURRENT_TENANT = new ThreadLocal<>();
- 在 Filter 的 doFilter() 中： CURRENT_TENANT.set(tenantIdFromRequest);
- 请求结束后（finally 块或 afterCompletion），务必调用 CURRENT_TENANT.remove(); 防止线程复用导致脏数据
结合 Spring 的 RequestContext 和 TenantContextHolder
避免裸用 ThreadLocal，推荐封装为上下文持有器（如 TenantContextHolder），并利用 Spring 的 RequestContextFilter 确保其生命周期与请求对齐：
Java Maven Common
下载
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
- 声明一个 @Component 类，提供 setTenantId()、getTenantId()、clear() 方法，内部委托给 ThreadLocal
- 在 Filter 中调用 tenantContextHolder.setTenantId(...)，并在 finally 中调用 clear()
- 业务层（Service/DAO）直接注入该 Holder 获取当前租户，无需层层透传参数
数据库层面的租户隔离联动
仅靠 ThreadLocal 存租户 ID 不够，需与数据访问层协同实现自动隔离：
立即学习“Java免费学习笔记（深入）”；
- MyBatis：通过 Interceptor 拦截 SQL，动态添加 WHERE tenant_id = ? 或改写表名（如 order_001）
- JPA/Hibernate：使用 @Filter + @FilterDef 定义租户过滤器，并在 EntityManager 初始化时启用；或借助 Hibernate 的 MultiTenantConnectionProvider 实现连接级隔离
- 注意：ThreadLocal 中的租户 ID 必须在 DAO 执行前已设置好，否则拦截逻辑无法获取
注意事项与常见陷阱
ThreadLocal 隔离是“线程内有效”，但现代框架大量使用异步、线程池、CompletableFuture，容易导致上下文丢失：
- 使用 @Async 或 ThreadPoolTaskExecutor 时，需自定义 TaskDecorator，将父线程的 Tenant ID 传递到子线程
- WebFlux（响应式）不适用 ThreadLocal，应改用 ReactiveSecurityContextHolder 或 ContextView 传递租户信息
- 禁止在 ThreadLocal 中存大对象或未序列化资源（如 Connection、InputStream），防止内存泄漏
- 单元测试时，每个 test 方法需手动 set() 和 remove()，或使用 @BeforeEach/@AfterEach 清理
