MyBatis Plus分页插件配置与常见问题解决

1. 问题背景与现状分析

作为一名长期使用MyBatis进行数据库开发的工程师，分页查询是我们日常工作中最常遇到的需求之一。在传统MyBatis中，实现分页通常需要手动编写limit语句或者使用RowBounds，这种方式不仅代码冗余，而且容易出错。MyBatis Plus作为MyBatis的增强工具，提供了开箱即用的分页插件，理论上可以让我们彻底告别手写分页SQL的烦恼。

然而在实际项目中，很多开发者（包括我自己早期使用时）都会遇到一个典型问题：明明按照文档配置了分页插件，但执行查询时却发现分页根本不生效，SQL中完全没有出现limit语句。这种情况往往让人困惑不已，最终不得不又退回手动编写limit的老路。

2. MyBatis Plus分页插件原理解析

2.1 分页插件的工作机制

MyBatis Plus的分页插件本质上是一个拦截器（Interceptor），它会在SQL语句执行前进行拦截，根据传入的分页参数自动修改最终的SQL语句。其核心工作原理可以分为以下几个步骤：

1. 当调用Page对象作为参数的查询方法时，分页插件会拦截这个请求
2. 插件会先执行一次count查询获取总记录数
3. 然后根据当前页码和每页大小计算出limit和offset值
4. 最后修改原始SQL，添加对应的limit语句

2.2 为什么分页会不生效？

根据我的项目经验，分页不生效通常有以下几个原因：

1. 分页插件未正确配置：这是最常见的原因，很多开发者只是简单添加了@Bean声明，但缺少必要的配置项
2. 使用了错误的分页方式：MyBatis Plus支持多种分页方式，混用会导致失效
3. 自定义SQL未正确处理：在XML中手写SQL时，如果没有使用MP的语法，插件无法识别
4. 版本兼容性问题：不同版本的MP对分页的支持可能有差异

3. 一行配置解决分页问题

3.1 正确配置分页插件

经过多次项目实践，我发现以下配置方式是最可靠且兼容性最好的：

java复制@Configuration
public class MybatisPlusConfig {
    
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 添加分页插件
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

这个配置的关键点在于：

1. 使用MybatisPlusInterceptor作为主拦截器
2. 通过addInnerInterceptor添加PaginationInnerInterceptor
3. 指定数据库类型（这里是MySQL）

3.2 分页查询的正确使用方式

配置好插件后，在Service层可以这样使用：

java复制public Page<User> getUserPage(int pageNum, int pageSize) {
    Page<User> page = new Page<>(pageNum, pageSize);
    return userMapper.selectPage(page, null);
}

或者使用Lambda方式：

java复制public Page<User> getUserPage(int pageNum, int pageSize) {
    Page<User> page = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<User> wrapper = Wrappers.lambdaQuery();
    wrapper.eq(User::getStatus, 1);
    return userMapper.selectPage(page, wrapper);
}

4. 常见问题与避坑指南

4.1 分页失效的典型场景

1. 自定义SQL未使用MP参数：
   错误示范：

   xml复制<select id="selectUserPage" resultType="User">
       SELECT * FROM user WHERE status = 1
   </select>
   

   正确写法：

   xml复制<select id="selectUserPage" resultType="User">
       SELECT * FROM user ${ew.customSqlSegment}
   </select>
   

2. 混用不同分页方式：
   避免同时使用PageHelper和MyBatis Plus的分页插件

3. Page参数位置错误：
   Page参数必须是方法的第一个参数

4.2 性能优化建议

1. 关闭不必要的count查询：
   如果不需要总记录数，可以这样创建Page对象：

   java复制Page<User> page = new Page<>(pageNum, pageSize, false);
   

2. 自定义count语句：
   对于复杂查询，可以单独指定count语句：

   xml复制<select id="selectUserPage" resultType="User">
       SELECT * FROM user ${ew.customSqlSegment}
   </select>
   <select id="selectUserPageCount" resultType="long">
       SELECT COUNT(1) FROM user ${ew.customSqlSegment}
   </select>
   

3. 合理设置分页大小：
   建议根据业务场景设置合理的maxLimit：

   java复制PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor();
   paginationInterceptor.setMaxLimit(500L);
   

5. 高级用法与最佳实践

5.1 多租户场景下的分页处理

在多租户系统中，分页查询需要特别注意租户隔离。建议这样处理：

java复制public Page<User> getUserPageByTenant(int pageNum, int pageSize, Long tenantId) {
    Page<User> page = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<User> wrapper = Wrappers.lambdaQuery();
    wrapper.eq(User::getTenantId, tenantId);
    return userMapper.selectPage(page, wrapper);
}

5.2 复杂联表查询分页

对于需要联表查询的场景，建议：

1. 使用DTO接收结果
2. 在XML中手写SQL但保留MP的分页参数
3. 确保主表分页而不是结果集分页

示例：

xml复制<select id="selectUserWithRolePage" resultType="UserRoleDTO">
    SELECT u.*, r.role_name 
    FROM user u LEFT JOIN role r ON u.role_id = r.id
    ${ew.customSqlSegment}
</select>

5.3 分布式环境下的分页一致性

在分布式系统中，分页查询可能会遇到数据一致性问题。建议：

1. 使用唯一排序字段确保分页稳定性
2. 对于实时性要求高的场景，考虑使用游标分页
3. 避免在大数据量下使用深分页（如pageNum>1000）

6. 版本适配与升级指南

6.1 不同版本的配置差异

1. 3.4.0以下版本：
   需要使用PaginationInterceptor：

   java复制@Bean
   public PaginationInterceptor paginationInterceptor() {
       return new PaginationInterceptor();
   }
   

2. 3.4.0及以上版本：
   使用新的MybatisPlusInterceptor方式（推荐）

6.2 升级注意事项

1. 从旧版升级时，需要修改配置类
2. 新版的分页行为可能略有不同，需要测试验证
3. 某些过时的API已被标记为@Deprecated

7. 调试技巧与问题排查

当分页不生效时，可以按照以下步骤排查：

1. 检查插件是否加载：
   在启动日志中搜索"MybatisPlusInterceptor"确认插件已加载

2. 开启SQL日志：
   在application.yml中添加：

   yaml复制logging:
     level:
       com.baomidou.mybatisplus: debug
   

3. 验证Page参数：
   确保Page对象被正确创建并传入

4. 检查SQL输出：
   观察最终执行的SQL是否包含limit语句

5. 版本兼容性检查：
   确认MyBatis Plus版本与Spring Boot版本的匹配关系

8. 替代方案对比

虽然MyBatis Plus分页插件很好用，但在某些特殊场景下，也可以考虑其他方案：

1. PageHelper：
   优点：使用简单，兼容性好
   缺点：与MyBatis Plus混用可能导致冲突

2. 物理分页 vs 逻辑分页：
   大数据量下，物理分页（limit）性能更好
   小数据量可以考虑逻辑分页（内存分页）

3. 游标分页：
   适合无限滚动场景，性能更好
   实现相对复杂

9. 实际项目中的经验分享

经过多个项目的实践，我总结出以下经验：

1. 统一分页参数：
   建议封装统一的PageParam对象：

   java复制@Data
   public class PageParam {
       private Integer pageNum = 1;
       private Integer pageSize = 10;
       private Boolean count = true;
   }
   

2. 全局分页限制：
   为防止恶意的大分页请求，建议设置全局最大分页大小：

   java复制@Bean
   public MybatisPlusInterceptor mybatisPlusInterceptor() {
       MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
       PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor();
       paginationInterceptor.setMaxLimit(1000L);
       interceptor.addInnerInterceptor(paginationInterceptor);
       return interceptor;
   }
   

3. 前端分页配合：
   建议与前端约定统一的响应格式：

   java复制@Data
   public class PageResult<T> {
       private Long total;
       private List<T> records;
       private Integer pageNum;
       private Integer pageSize;
   }
   

10. 性能测试与对比数据

为了验证分页插件的性能，我做了以下测试：

测试环境：

• MySQL 8.0
• 100万条测试数据
• 普通配置的服务器

测试结果：

从测试结果可以看出：

1. 对于常规分页，limit方式性能最好
2. 深分页（如1000页以后）性能下降明显
3. 游标分页在深分页场景下表现最优

11. 特殊场景处理方案

11.1 多数据源分页

在多数据源环境下，需要为每个数据源单独配置分页插件：

java复制@Bean
public MybatisPlusInterceptor db1Interceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
    return interceptor;
}

@Bean
public MybatisPlusInterceptor db2Interceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.ORACLE));
    return interceptor;
}

11.2 存储过程分页

如果使用存储过程实现分页，需要特殊处理：

1. 在Mapper接口中定义方法：

   java复制@Select("{call sp_user_pagination(#{pageNum,mode=IN},#{pageSize,mode=IN},#{total,mode=OUT,jdbcType=INTEGER})}")
   @Options(statementType = StatementType.CALLABLE)
   List<User> selectUserByPage(Map<String, Object> params);
   

2. 在Service层调用：

   java复制public Page<User> getUserPageByProcedure(int pageNum, int pageSize) {
       Map<String, Object> params = new HashMap<>();
       params.put("pageNum", pageNum);
       params.put("pageSize", pageSize);
       userMapper.selectUserByPage(params);
       
       Page<User> page = new Page<>(pageNum, pageSize);
       page.setRecords((List<User>) params.get("result"));
       page.setTotal(Long.parseLong(params.get("total").toString()));
       return page;
   }
   

12. 未来演进与社区动态

MyBatis Plus分页功能仍在持续优化中，根据官方路线图，未来可能会支持：

1. 更智能的分页策略选择
2. 对更多数据库类型的原生支持
3. 与Spring Data的更深度整合
4. 响应式编程支持

建议定期关注官方GitHub仓库和更新日志，及时获取最新特性。