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

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改为setMaxLimit2. 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 配置新版分页插件新版配置需要两个关键BeanConfiguration 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; } }关键参数说明参数名类型默认值说明setDbTypeDbType无必须设置如DbType.MYSQLsetMaxLimitLong500单页最大记录数-1表示不限制setOptimizeJoinbooleanfalse是否优化COUNT SQL中的JOINsetOverflowbooleanfalse请求页数超过总页数时的处理方式2.3 验证配置是否生效编写简单的测试代码验证分页功能Test public void testPagination() { PageUser 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 idpaginationInterceptor classcom.baomidou.mybatisplus.extension.plugins.PaginationInterceptor property namelimit value1000/ /bean3.2 添加新版配置!-- 新版分页拦截器 -- bean idpaginationInnerInterceptor classcom.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor property namedbType valueMYSQL/ property namemaxLimit value1000/ property nameoptimizeJoin valuetrue/ /bean !-- MyBatis-Plus主拦截器 -- bean idmybatisPlusInterceptor classcom.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor property nameinterceptors list ref beanpaginationInnerInterceptor/ /list /property /bean4. 高级配置与最佳实践4.1 多数据库支持配置如果项目需要支持多种数据库可以动态设置dbTypeBean 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; }4.3 常见问题排查问题1分页查询结果不正确检查是否设置了正确的dbType确认SQL中是否包含ORDER BY语句问题2COUNT查询性能差尝试设置optimizeJointrue考虑使用自定义COUNT SQL问题3与其他插件冲突调整插件添加顺序检查是否有重复配置5. 版本兼容性说明MyBatis-Plus分页插件各版本差异版本范围插件类名配置方式备注3.0-3.4PaginationInterceptor直接配置已废弃3.5PaginationInnerInterceptor通过MybatisPlusInterceptor配置当前推荐升级建议小版本升级(如3.4.3→3.4.4)通常不会影响分页功能主版本升级(如3.4→3.5)需要按本文方案调整配置建议在测试环境充分验证后再部署到生产环境在实际项目中我们团队从3.4升级到3.5时发现分页问题是最常见的兼容性问题之一。通过合理配置新的拦截器链机制不仅解决了兼容性问题还获得了更好的扩展性可以方便地添加其他功能插件。