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

MyBatis-Plus 3.5升级后，分页插件PaginationInterceptor报错？手把手教你换成PaginationInnerInterceptor

news 2026/4/23 13:41:01

MyBatis-Plus 3.5升级后分页插件报错全解析：从问题定位到完美修复

最近在升级MyBatis-Plus到3.5版本后，不少开发者发现原本运行良好的分页功能突然报错，控制台抛出各种异常信息。这实际上是MyBatis-Plus团队对分页机制进行了重构导致的兼容性问题。本文将带你深入分析问题根源，并提供两种主流配置方式的完整解决方案。

1. 问题现象与错误分析

升级到MyBatis-Plus 3.5后，最常见的分页相关错误包括：

java.lang.NoClassDefFoundError: com/baomidou/mybatisplus/extension/plugins/PaginationInterceptor

或者

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'paginationInterceptor'

这些错误的根本原因是3.5版本对分页插件进行了架构调整：

旧版(3.4及之前)：直接使用PaginationInterceptor类
新版(3.5+)：引入插件拦截器链机制，分页功能由PaginationInnerInterceptor实现，并通过MybatisPlusInterceptor统一管理

关键变化点：

包路径变更：从plugins包移动到plugins.inner子包
配置方式变化：需要先创建MybatisPlusInterceptor实例
方法命名调整：如setLimit改为setMaxLimit

2. Java配置方式完整解决方案

对于使用Java配置的Spring Boot项目，以下是详细的迁移步骤：

2.1 移除旧版配置

首先删除或注释掉原有的PaginationInterceptor配置代码：

// 旧版配置 - 需要删除或注释 @Bean public PaginationInterceptor paginationInterceptor() { PaginationInterceptor interceptor = new PaginationInterceptor(); interceptor.setLimit(1000); interceptor.setCountSqlParser(new JsqlParserCountOptimize(true)); return interceptor; }

2.2 配置新版分页插件

新版配置需要两个关键Bean：

@Configuration @MapperScan("com.yourpackage.mapper") public class MybatisPlusConfig { /** * 新版分页插件配置 */ @Bean public PaginationInnerInterceptor paginationInnerInterceptor() { PaginationInnerInterceptor interceptor = new PaginationInnerInterceptor(); // 设置数据库类型(重要!) interceptor.setDbType(DbType.MYSQL); // 设置单页最大记录数(-1表示不限制) interceptor.setMaxLimit(1000L); // 开启count查询优化 interceptor.setOptimizeJoin(true); // 溢出总页数后是否处理(默认false) interceptor.setOverflow(false); return interceptor; } /** * 将分页插件添加到拦截器链 */ @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(paginationInnerInterceptor()); return interceptor; } }

关键参数说明：

参数名	类型	默认值	说明
setDbType	DbType	无	必须设置，如DbType.MYSQL
setMaxLimit	Long	500	单页最大记录数，-1表示不限制
setOptimizeJoin	boolean	false	是否优化COUNT SQL中的JOIN
setOverflow	boolean	false	请求页数超过总页数时的处理方式

2.3 验证配置是否生效

编写简单的测试代码验证分页功能：

@Test public void testPagination() { Page<User> page = new Page<>(1, 10); userMapper.selectPage(page, null); System.out.println("总记录数: " + page.getTotal()); System.out.println("当前页记录: " + page.getRecords()); }

3. XML配置方式解决方案

对于仍在使用Spring XML配置的项目，可以按以下方式调整：

3.1 删除旧版配置

移除原有的PaginationInterceptorbean定义：

<!-- 旧版配置 - 需要删除 --> <bean id="paginationInterceptor" class="com.baomidou.mybatisplus.extension.plugins.PaginationInterceptor"> <property name="limit" value="1000"/> </bean>

3.2 添加新版配置

<!-- 新版分页拦截器 --> <bean id="paginationInnerInterceptor" class="com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor"> <property name="dbType" value="MYSQL"/> <property name="maxLimit" value="1000"/> <property name="optimizeJoin" value="true"/> </bean> <!-- MyBatis-Plus主拦截器 --> <bean id="mybatisPlusInterceptor" class="com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor"> <property name="interceptors"> <list> <ref bean="paginationInnerInterceptor"/> </list> </property> </bean>

4. 高级配置与最佳实践

4.1 多数据库支持配置

如果项目需要支持多种数据库，可以动态设置dbType：

@Bean public PaginationInnerInterceptor paginationInnerInterceptor() { PaginationInnerInterceptor interceptor = new PaginationInnerInterceptor(); // 根据数据源自动判断数据库类型 interceptor.setDbType(DbType.getDbType(dataSource)); // ...其他配置 return interceptor; }

4.2 性能优化建议

合理设置maxLimit：
- 避免设置过大值导致内存溢出
- 推荐根据业务需求设置合理上限

COUNT查询优化：

// 对于复杂SQL，可以关闭COUNT优化 interceptor.setOptimizeJoin(false);

多插件配置顺序：

@Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 先添加分页插件 interceptor.addInnerInterceptor(paginationInnerInterceptor()); // 再添加其他插件(如乐观锁) interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; }