ruoyi-cloud 集成 mybatis-plus 多租户插件：从配置到实战避坑指南
1. 为什么需要多租户插件？
在开发SaaS应用时，数据隔离是最基础也是最重要的需求之一。想象一下，你开发了一个CRM系统，A公司和B公司同时使用你的系统，但A公司绝对不能看到B公司的客户数据，这就是典型的多租户场景。
我去年接手过一个项目，客户要求两周内实现多租户隔离。当时尝试了几种方案：独立数据库（成本太高）、共享数据库独立Schema（维护麻烦），最终选择了共享数据库共享表的方案，这就是Mybatis-Plus多租户插件的用武之地。
Mybatis-Plus的多租户插件通过在SQL中自动注入租户条件（比如WHERE tenant_id = 'A'）来实现数据隔离。这种方式既保证了数据安全，又不会增加太多开发负担。在RuoYi-Cloud这种成熟的微服务框架中集成该插件，能快速为你的SaaS应用加上"数据隔离盾"。
2. 环境准备与依赖管理
2.1 版本兼容性：躲开第一个大坑
我最开始集成时被版本冲突折腾得够呛。Mybatis-Plus和PageHelper都依赖jsqlparser，但版本不一致会导致经典的ClassCastException：
// 典型报错 net.sf.jsqlparser.statement.select.SetOperationList cannot be cast to net.sf.jsqlparser.statement.select.PlainSelect经过多次测试，总结出黄金组合：
<properties> <!-- Mybatis-Plus要主导jsqlparser版本 --> <com.baomidou.mybatisplus.version>3.5.2</com.baomidou.mybatisplus.version> <!-- PageHelper版本要低于Mybatis-Plus --> <pagehelper.boot.version>1.4.2</pagehelper.boot.version> </properties>2.2 依赖配置技巧
在dependencyManagement中声明依赖时，记得给PageHelper做排除：
<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper-spring-boot-starter</artifactId> <exclusions> <exclusion> <artifactId>mybatis-spring</artifactId> <groupId>org.mybatis</groupId> </exclusion> <exclusion> <artifactId>mybatis</artifactId> <groupId>org.mybatis</groupId> </exclusion> </exclusions> </dependency>这样能避免Mybatis核心库的版本冲突。建议新建一个mybatis-plus模块专门管理相关依赖，其他模块按需引入。
3. 核心配置实战
3.1 插件配置类详解
配置类的编写有几个关键点需要注意：
@Configuration @EnableConfigurationProperties(MyTenantConfigProperties.class) @AllArgsConstructor // 推荐使用构造器注入 public class MybatisPlusConfig { private final MyTenantConfigProperties tenantConfig; @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 注意插件顺序：多租户插件必须在前！ interceptor.addInnerInterceptor(new TenantLineInnerInterceptor( new CustomTenantLineHandler(tenantConfig))); // 分页插件要放在后面 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }踩坑提醒：
- 插件顺序影响SQL生成，多租户插件必须最先添加
- 避免使用
@Autowired字段注入，推荐构造器注入 - 分页插件要设置
DbType，否则某些复杂SQL会解析错误
3.2 租户处理器编写秘籍
自定义处理器是业务逻辑的核心，这里分享我的实战代码：
@Component @RequiredArgsConstructor public class CustomTenantLineHandler implements TenantLineHandler { private final MyTenantConfigProperties config; private final SecurityUtils securityUtils; // 你的权限工具类 @Override public String getTenantIdColumn() { return config.getColumn(); // 默认tenant_id } @Override public boolean ignoreTable(String tableName) { // 超级管理员跳过过滤 if (securityUtils.isSuperAdmin()) { return true; } // 配置表不参与租户过滤 return config.getTables().contains(tableName); } @Override public Expression getTenantId() { // 从登录信息获取租户ID return new StringValue(securityUtils.getTenantId()); } }避坑指南：
- 对于
sys_config这类系统表，一定要配置忽略 - 租户ID建议从ThreadLocal获取，避免跨线程问题
- 日志打印租户ID方便调试，但生产环境记得关闭
4. 动态配置与Nacos集成
4.1 配置热更新方案
通过Nacos实现配置动态刷新：
@Data @RefreshScope @ConfigurationProperties(prefix = "ruoyi.tenant") public class MyTenantConfigProperties { private String column = "tenant_id"; private List<String> tables = new ArrayList<>(); }对应的Nacos配置：
ruoyi: tenant: column: tenant_code # 支持修改租户字段名 tables: - sys_config - sys_dict_data实测效果：
- 修改配置后30秒内生效
- 新增忽略表不需要重启服务
- 租户字段名可随时变更
4.2 代码生成器改造
RuoYi的代码生成器需要做两处修改：
- 实体类自动添加租户字段注解：
@TableField(fill = FieldFill.INSERT) private String tenantId;- Mapper模板中加入租户过滤：
<where> ${ew.sqlSegment} AND tenant_id = #{tenantId} </where>建议新建一个代码生成模板，避免污染原有模板。我在实际项目中专门创建了tenant-mapper.xml.vm模板文件。
5. 常见问题排查手册
问题1：新增数据时报错tenant_id不能为null
- 检查实体类是否有
@TableField(fill = FieldFill.INSERT) - 确认
MetaObjectHandler配置了自动填充
问题2：多表联查时租户条件丢失
- 使用LEFT JOIN时要手动添加ON条件：
LEFT JOIN table_b b ON a.id = b.a_id AND b.tenant_id = 'xxx'问题3：批量插入性能差
- 改用Mybatis-Plus的
saveBatch方法 - 开启批处理模式：
mybatis-plus: global-config: db-config: logic-delete-field: delFlag configuration: default-executor-type: batch问题4：分布式事务问题
- 建议使用Seata时关闭多租户插件对undo_log表的过滤
- 在handler中特殊处理undo_log表：
if ("undo_log".equals(tableName)) { return true; }记得在测试环境充分验证这些场景。我在上线前专门编写了20多个集成测试用例，覆盖了各种边界情况。