MyBatis-Plus 3.5分页插件全指南从原理到避坑实战最近在技术社区看到不少开发者反馈MyBatis-Plus升级到3.5版本后分页功能突然失效这其实是框架架构调整带来的配置变化。作为深度使用MyBatis-Plus的开发者我完整经历了从旧版到新版的迁移过程今天就把这些实战经验系统梳理出来。1. 为什么你的分页突然失效了MyBatis-Plus在3.4/3.5版本进行了架构重构最显著的变化就是将原先独立的插件体系改为拦截器链模式。这意味着旧版直接注册PaginationInterceptor的方式不再适用新版必须通过MybatisPlusInterceptor统一管理所有插件分页实现类更名为PaginationInnerInterceptor典型报错表现// 控制台无分页SQL生成 SELECT * FROM user LIMIT ? // 返回结果未分页获取到全部数据常见配置误区包括直接复制旧版配置代码未做适配忘记将分页插件添加到拦截器链错误地同时注册了新旧两种插件2. 新版分页插件核心配置详解2.1 基础Java配置方案以下是经过生产验证的标准配置模板Configuration MapperScan(com.yourpackage.mapper) public class MybatisPlusConfig { /** * 新版分页插件 (3.5) */ Bean public PaginationInnerInterceptor paginationInnerInterceptor() { PaginationInnerInterceptor interceptor new PaginationInnerInterceptor(); // 数据库类型建议显式声明 interceptor.setDbType(DbType.MYSQL); // 单页最大记录数(-1表示不限制) interceptor.setMaxLimit(1000L); // 开启count查询优化 interceptor.setOptimizeJoin(true); return interceptor; } /** * 必须将分页插件添加到拦截器链 */ Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(paginationInnerInterceptor()); return interceptor; } }关键参数说明参数类型默认值建议设置dbTypeDbType自动检测生产环境建议显式指定maxLimitLong500根据业务调整-1表示不限制optimizeJoinBooleanfalse关联查询时建议开启2.2 XML配置方案适合传统项目对于仍在使用Spring XML配置的项目bean idpaginationInnerInterceptor classcom.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor property namedbType valueMYSQL/ /bean bean idmybatisPlusInterceptor classcom.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor property nameinterceptors list ref beanpaginationInnerInterceptor/ /list /property /bean3. 高级配置与性能优化3.1 多数据源分页适配当项目使用多数据源时需要针对不同数据库配置对应的分页插件Bean ConditionalOnProperty(prefix spring.datasource, name primary) public PaginationInnerInterceptor mysqlPagination() { PaginationInnerInterceptor interceptor new PaginationInnerInterceptor(DbType.MYSQL); interceptor.setOverflow(true); // 超出页数返回第一页 return interceptor; } Bean ConditionalOnProperty(prefix spring.datasource, name secondary) public PaginationInnerInterceptor oraclePagination() { return new PaginationInnerInterceptor(DbType.ORACLE); }3.2 分页性能优化技巧Count查询优化// 对于单表查询可以关闭count优化 interceptor.setOptimizeJoin(false); // 复杂查询建议使用自定义count语句 Select(SELECT * FROM user WHERE ...) Select(SELECT COUNT(1) FROM user WHERE ...) PageUser selectPage(Page? page, Param(param) QueryParam param);页面溢出处理// 请求页码超过总页数时是否回到首页 interceptor.setOverflow(false); // 配合前端处理 if (page.getCurrent() page.getPages()) { throw new BusinessException(页码超出范围); }4. 验证与调试指南4.1 配置有效性检查通过以下步骤确认分页是否生效在Controller中添加测试接口GetMapping(/testPage) public PageUser testPage(RequestParam(defaultValue 1) int current) { return userService.page(new Page(current, 10)); }观察控制台SQL输出-- 应该看到LIMIT子句 SELECT * FROM user LIMIT 10 -- 以及自动生成的count查询 SELECT COUNT(1) FROM user4.2 常见问题排查问题现象分页查询返回全部记录检查拦截器是否注册到Spring容器确认MybatisPlusInterceptor包含分页插件问题现象count查询报错复杂SQL可能需要关闭optimizeJoin考虑使用自定义count语句问题现象分页参数未生效检查Page参数是否正确传递确认没有其他拦截器修改了SQL5. 最佳实践与避坑指南在实际项目迭代中我们总结了这些经验版本兼容建议3.5.0-3.5.3存在一些边界case问题推荐使用3.5.3稳定版本事务注意事项// 分页查询建议放在只读事务中 Transactional(readOnly true) public PageUser queryPage(PageQuery query) { // ... }前端协作规范// 推荐分页响应格式 { records: [...], total: 100, size: 10, current: 1, pages: 10 }特殊场景处理// 手动分页示例 IPageUser manualPage new Page(1, 10); ListUser records userMapper.selectByCustomQuery(manualPage); manualPage.setRecords(records); return manualPage;最近在金融项目中迁移到MyBatis-Plus 3.5.4时发现当使用Oracle数据库时如果不显式设置dbType会导致分页语法错误。这个坑花了两小时才排查出来所以特别提醒大家多数据源环境下一定要明确指定数据库类型。