MyBatis Plus多租户实战：如何用TenantLineHandler实现数据隔离（附完整代码）

MyBatis Plus多租户架构深度实践：从TenantLineHandler到生产级解决方案

在当今SaaS服务盛行的时代，多租户架构已成为企业级应用的标配需求。作为Java生态中最受欢迎的ORM框架之一，MyBatis Plus通过TenantLineHandler提供了一套优雅的多租户解决方案。本文将带您深入实践，不仅涵盖基础实现，更会分享我在多个大型项目中总结出的实战经验与避坑指南。

1. 多租户架构的核心设计考量

多租户（Multi-tenancy）的本质是在单一应用实例中为多个客户（租户）提供服务，同时确保数据隔离。在开始编码前，我们需要明确几个关键设计决策：

三种主流的多租户数据隔离方案对比

提示：90%的中大型SaaS项目会选择"共享数据库共享表"方案，这也是MyBatis Plus TenantLineHandler主要支持的场景。

在实际项目中，我们还需要考虑：

• 租户标识的存储与传递（建议使用ThreadLocal）
• 公共表与租户表的区分策略
• 分布式环境下的租户上下文一致性
• 性能影响评估（特别是关联查询场景）

2. TenantLineHandler的完整实现剖析

让我们从基础实现开始，逐步构建一个生产可用的多租户解决方案。

2.1 租户上下文管理

首先需要建立租户信息的传递机制。我推荐使用ThreadLocal结合Filter的方案：

public class TenantContext { private static final ThreadLocal<String> CURRENT_TENANT = new ThreadLocal<>(); public static void setCurrentTenant(String tenantId) { CURRENT_TENANT.set(tenantId); } public static String getCurrentTenant() { return CURRENT_TENANT.get(); } public static void clear() { CURRENT_TENANT.remove(); } } // 在Spring Web拦截器中设置租户ID public class TenantInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String tenantId = request.getHeader("X-Tenant-ID"); if (StringUtils.isNotBlank(tenantId)) { TenantContext.setCurrentTenant(tenantId); } return true; } @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { TenantContext.clear(); } }

2.2 核心TenantLineHandler实现

以下是增强版的CustomTenantLineHandler实现，包含多项生产环境必需的优化：

public class EnhancedTenantLineHandler implements TenantLineHandler { // 租户ID列名（可配置化） private String tenantIdColumn = "tenant_id"; // 忽略租户过滤的表名集合 private Set<String> ignoreTables = new HashSet<>(Arrays.asList( "system_config", "common_code", "metadata_table" )); @Override public Expression getTenantId() { String tenantId = TenantContext.getCurrentTenant(); if (StringUtils.isBlank(tenantId)) { throw new BusinessException("租户上下文不存在"); } return new StringValue(tenantId); } @Override public String getTenantIdColumn() { return tenantIdColumn; } @Override public boolean ignoreTable(String tableName) { // 动态判断是否忽略租户过滤 return ignoreTables.contains(tableName.toLowerCase()) || tableName.startsWith("global_"); } // 支持动态配置 public void setTenantIdColumn(String tenantIdColumn) { this.tenantIdColumn = tenantIdColumn; } public void setIgnoreTables(String tables) { this.ignoreTables = Arrays.stream(tables.split(",")) .map(String::trim) .collect(Collectors.toSet()); } }

2.3 MyBatis Plus配置集成

在最新版本的MyBatis Plus中，配置方式有所变化：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 租户插件 TenantLineInnerInterceptor tenantInterceptor = new TenantLineInnerInterceptor(); tenantInterceptor.setTenantLineHandler(enhancedTenantLineHandler()); interceptor.addInnerInterceptor(tenantInterceptor); interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); return interceptor; } @Bean public EnhancedTenantLineHandler enhancedTenantLineHandler() { EnhancedTenantLineHandler handler = new EnhancedTenantLineHandler(); handler.setTenantIdColumn("tenant_code"); handler.setIgnoreTables("system_config,common_code"); return handler; } }

3. 高级场景与性能优化

多租户实现后，我们还需要解决一些进阶问题。

3.1 分布式系统下的租户传递

在微服务架构中，租户信息需要跨服务传递。建议采用以下方案：

1. HTTP头传递：所有服务间调用携带X-Tenant-ID头
2. MQ消息扩展：在消息属性中添加tenantId字段
3. Feign拦截器自动处理租户信息

public class TenantFeignInterceptor implements RequestInterceptor { @Override public void apply(RequestTemplate template) { String tenantId = TenantContext.getCurrentTenant(); if (StringUtils.isNotBlank(tenantId)) { template.header("X-Tenant-ID", tenantId); } } }

3.2 多租户下的SQL性能优化

租户条件自动追加可能影响查询性能，特别是：

• 多表JOIN查询
• 大数据量表的分页查询
• 复杂子查询场景

优化建议：

1. 为tenant_id列建立索引
2. 避免全表扫描的租户查询
3. 对大数据量表考虑分区表策略
4. 定期执行租户数据统计任务

-- 建议的索引创建方式 CREATE INDEX idx_tenant ON user(tenant_id); CREATE INDEX idx_tenant_status ON order(tenant_id, status);

4. 测试策略与常见问题排查

确保多租户功能正确性需要特别的测试方法。

4.1 单元测试方案

@SpringBootTest public class TenantTest { @Autowired private UserMapper userMapper; @Test public void testTenantIsolation() { // 模拟租户A上下文 TenantContext.setCurrentTenant("tenantA"); userMapper.insert(new User("User1")); // 模拟租户B上下文 TenantContext.setCurrentTenant("tenantB"); Assert.assertEquals(0, userMapper.selectCount(null)); // 验证公共表不受影响 long configCount = systemConfigMapper.selectCount(null); Assert.assertTrue(configCount > 0); } }

4.2 常见问题排查清单

1. SQL中缺少租户条件

   • 检查TenantLineHandler是否正确配置
   • 验证表名是否被意外过滤

2. 跨租户数据泄露

   • 检查ThreadLocal是否及时清理
   • 验证异步任务中的上下文传递

3. 性能下降明显

   • 检查tenant_id列索引
   • 分析执行计划

4. 公共表被错误过滤

   • 验证doTableFilter逻辑
   • 检查表名大小写问题

在最近的一个电商平台项目中，我们遇到了一个典型问题：在批量导入数据时，由于没有显式设置租户ID，导致数据被错误地归属到默认租户。最终通过添加以下检查代码解决了问题：

public void batchImport(List<Product> products) { if (TenantContext.getCurrentTenant() == null) { throw new IllegalStateException("批量操作必须指定租户"); } // 实际导入逻辑 }