当前位置：首页 > news >正文

手把手教你修复MybatisPlus 3.5.x分页与租户注解的冲突问题

news 2026/6/16 16:14:23

手把手教你修复MybatisPlus 3.5.x分页与租户注解的冲突问题

最近在Spring Boot项目中整合MybatisPlus 3.5.x时，不少开发者反馈一个棘手的问题：当Mapper方法同时使用分页参数和@InterceptorIgnore(tenantLine = "true")注解时，租户过滤会意外失效。这个问题看似简单，实则涉及MybatisPlus底层插件的执行机制，如果不彻底理解原理，很容易陷入反复调试的困境。

1. 问题现象与根源分析

在实际项目中，我们经常会遇到这样的场景：某个列表查询需要分页展示，但同时又不希望受到租户隔离的限制。按照MybatisPlus的常规用法，开发者可能会这样编写代码：

@InterceptorIgnore(tenantLine = "true") Page<SysEnterpriseBinding> listPage(Page<SysEnterpriseBinding> page, @Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper);

表面上看这段代码没有任何问题，但在实际执行时却发现租户过滤依然生效，导致查询结果不符合预期。

问题根源在于分页插件的执行流程：

MybatisPlus分页插件会先执行方法名_COUNT查询获取总数
只有当总数大于0时，才会继续执行原始方法查询数据
@InterceptorIgnore注解的缓存是基于原始方法名存储的
执行_COUNT方法时，由于缓存中找不到对应记录，导致租户过滤重新生效

这个问题的本质是注解缓存机制与分页执行流程的不匹配。理解这一点对后续解决方案的选择至关重要。

2. 主流解决方案对比

针对这个问题，社区和官方文档中主要提到了三种解决方案，每种方案各有优缺点：

2.1 伪_COUNT方法方案

这是最直接也最被推荐的解决方案，具体实现如下：

@InterceptorIgnore(tenantLine = "true") Page<SysEnterpriseBinding> listPage(Page<SysEnterpriseBinding> page, @Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper); @InterceptorIgnore(tenantLine = "true") Long listPage_COUNT(@Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper);

优点：

改动量最小，只需添加一个方法声明
不需要修改XML映射文件
完全遵循MybatisPlus的设计理念

缺点：

需要为每个分页方法都添加对应的_COUNT方法
方法签名必须严格匹配（参数列表要去掉Page参数）

2.2 自定义分页插件方案

对于需要更灵活控制的场景，可以考虑自定义分页插件：

public class CustomPaginationInterceptor extends PaginationInnerInterceptor { @Override public void beforeQuery(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) { // 自定义处理逻辑 } }

优点：

可以统一处理所有分页查询
灵活性高，可以加入更多自定义逻辑

缺点：

实现复杂度高，需要深入理解Mybatis插件机制
可能会影响其他插件的执行顺序

2.3 调整InterceptorIgnore缓存逻辑

第三种方案是修改InterceptorIgnoreHelper的缓存逻辑：

public class CustomInterceptorIgnoreHelper { public static boolean willIgnoreTenantLine(String id) { // 自定义缓存查找逻辑 } }

优点：

可以一劳永逸解决问题
不依赖具体方法命名

缺点：

需要修改MybatisPlus核心逻辑
升级版本时可能需要重新适配

3. 详细实施指南

对于大多数项目，我们推荐使用第一种方案，下面是具体实施步骤：

3.1 添加伪_COUNT方法

在原有分页方法所在的Mapper接口中，添加一个同名但带有_COUNT后缀的方法
确保新方法的参数列表与原始方法一致（去掉Page参数）
为该方法添加相同的@InterceptorIgnore注解

public interface SysEnterpriseBindingMapper extends BaseMapper<SysEnterpriseBinding> { @InterceptorIgnore(tenantLine = "true") Page<SysEnterpriseBinding> listPage(Page<SysEnterpriseBinding> page, @Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper); @InterceptorIgnore(tenantLine = "true") Long listPage_COUNT(@Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper); }

3.2 注意事项

实施过程中需要特别注意以下几点：

方法签名一致性：
- _COUNT方法的参数必须与原始方法去掉Page参数后的签名完全一致
- 包括@Param注解的使用也要完全相同
XML映射文件：
- 不需要为_COUNT方法编写实际的SQL映射
- MybatisPlus会自动处理计数查询
返回类型：
- _COUNT方法必须返回Long类型
- 这是分页插件的硬性要求
注解一致性：
- _COUNT方法上的@InterceptorIgnore注解配置必须与原始方法完全一致
- 包括所有属性值都要相同

4. 验证与测试

实施修复后，必须进行充分验证：

4.1 单元测试验证

编写专门的测试用例来验证修复效果：

@Test public void testListPageIgnoreTenant() { Page<SysEnterpriseBinding> page = new Page<>(1, 10); QueryWrapper<SysEnterpriseBinding> wrapper = new QueryWrapper<>(); Page<SysEnterpriseBinding> result = sysEnterpriseBindingMapper.listPage(page, wrapper); // 验证查询结果是否包含所有租户的数据 assertThat(result.getRecords().size()).isGreaterThan(0); }

4.2 SQL日志检查

通过查看执行的SQL语句来确认租户条件是否被正确忽略：

==> Preparing: SELECT COUNT(*) FROM sys_enterprise_binding ==> Parameters: <== Columns: COUNT(*) <== Row: 100 ==> Preparing: SELECT id,name,... FROM sys_enterprise_binding LIMIT ? ==> Parameters: 10(Integer)

关键点检查：

SQL中不应包含tenant_id条件
两条SQL都应该正常执行

5. 高级应用场景

对于更复杂的场景，可能需要一些额外的处理技巧：

5.1 动态忽略租户过滤

有时候我们需要根据条件动态决定是否忽略租户过滤：

@InterceptorIgnore(tenantLine = "true", value = "判断条件") Page<SysEnterpriseBinding> dynamicListPage(Page<SysEnterpriseBinding> page, @Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper);

5.2 多租户系统中的特殊处理

在多租户系统中，可能需要对某些特殊租户放宽限制：

@InterceptorIgnore(tenantLine = "true", ifDynamic = "tenantId != 1") Page<SysEnterpriseBinding> specialListPage(Page<SysEnterpriseBinding> page, @Param("ew") QueryWrapper<SysEnterpriseBinding> wrapper);