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

MyBatis Plus多租户架构深度实践从TenantLineHandler到生产级解决方案在当今SaaS服务盛行的时代多租户架构已成为企业级应用的标配需求。作为Java生态中最受欢迎的ORM框架之一MyBatis Plus通过TenantLineHandler提供了一套优雅的多租户解决方案。本文将带您深入实践不仅涵盖基础实现更会分享我在多个大型项目中总结出的实战经验与避坑指南。1. 多租户架构的核心设计考量多租户Multi-tenancy的本质是在单一应用实例中为多个客户租户提供服务同时确保数据隔离。在开始编码前我们需要明确几个关键设计决策三种主流的多租户数据隔离方案对比方案类型数据库级别表设计优缺点独立数据库每个租户独立数据库相同表结构隔离性最强成本最高共享数据库独立Schema同一数据库不同Schema相同表结构中等隔离中等成本共享数据库共享表同一数据库同一Schema增加tenant_id列成本最低需严格代码控制提示90%的中大型SaaS项目会选择共享数据库共享表方案这也是MyBatis Plus TenantLineHandler主要支持的场景。在实际项目中我们还需要考虑租户标识的存储与传递建议使用ThreadLocal公共表与租户表的区分策略分布式环境下的租户上下文一致性性能影响评估特别是关联查询场景2. TenantLineHandler的完整实现剖析让我们从基础实现开始逐步构建一个生产可用的多租户解决方案。2.1 租户上下文管理首先需要建立租户信息的传递机制。我推荐使用ThreadLocal结合Filter的方案public class TenantContext { private static final ThreadLocalString 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 SetString 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 分布式系统下的租户传递在微服务架构中租户信息需要跨服务传递。建议采用以下方案HTTP头传递所有服务间调用携带X-Tenant-ID头MQ消息扩展在消息属性中添加tenantId字段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查询大数据量表的分页查询复杂子查询场景优化建议为tenant_id列建立索引避免全表扫描的租户查询对大数据量表考虑分区表策略定期执行租户数据统计任务-- 建议的索引创建方式 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 常见问题排查清单SQL中缺少租户条件检查TenantLineHandler是否正确配置验证表名是否被意外过滤跨租户数据泄露检查ThreadLocal是否及时清理验证异步任务中的上下文传递性能下降明显检查tenant_id列索引分析执行计划公共表被错误过滤验证doTableFilter逻辑检查表名大小写问题在最近的一个电商平台项目中我们遇到了一个典型问题在批量导入数据时由于没有显式设置租户ID导致数据被错误地归属到默认租户。最终通过添加以下检查代码解决了问题public void batchImport(ListProduct products) { if (TenantContext.getCurrentTenant() null) { throw new IllegalStateException(批量操作必须指定租户); } // 实际导入逻辑 }