1. 项目背景与问题定位在Java持久层开发中MyBatis-Plus和PageHelper都是高频使用的工具库。前者提供了强大的CRUD封装后者则是分页查询的利器。但当两者在同一个项目中并存时分页功能就会出现打架现象——明明SQL正确添加了LIMIT子句但分页元数据当前页码、总页数等却显示异常。最近在重构一个老项目时就踩了这个坑使用PageHelper.startPage()后用MyBatis-Plus的selectVoList查询结果PageInfo对象中的pageNum始终为1isLastPage永远返回true。通过DEBUG发现虽然SQL确实被修改成分页格式但分页上下文信息在传递过程中丢失了。2. 核心冲突原理分析2.1 PageHelper的工作机制PageHelper通过MyBatis的Interceptor接口实现分页拦截。其核心逻辑是在Executor.query()方法执行前通过ThreadLocal保存分页参数修改BoundSql对象添加LIMIT/OFFSET语句执行查询后用Page对象包装结果并清理ThreadLocal关键点在于它依赖标准的MyBatis查询执行流程来维护分页上下文。2.2 MyBatis-Plus的扩展方法MyBatis-Plus的selectVoList等扩展方法走的是另一套执行路径通过AbstractMethod封装SQL构建逻辑使用SqlInjector动态注入方法最终通过DefaultSqlSession执行自定义SQL这种机制绕过了PageHelper依赖的拦截点导致分页参数无法正确传递到PageInfo。3. 四种兼容方案实测3.1 方案一统一使用MyBatis-Plus分页推荐// 配置分页插件 Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); return interceptor; } // 查询示例 PageUserVO page new Page(1, 10); LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.eq(User::getStatus, 1); mapper.selectVoPage(page, wrapper); // 获取分页信息 page.getCurrent(); // 当前页 page.getPages(); // 总页数实测建议PaginationInnerInterceptor建议指定数据库类型如new PaginationInnerInterceptor(DbType.MYSQL)3.2 方案二自定义XML映射文件!-- UserMapper.xml -- select idselectVoPage resultTypeUserVO SELECT id, name FROM user where ${ew.sqlSegment} /where /select// Java调用 PageHelper.startPage(1, 10); ListUserVO list userMapper.selectVoPage(wrapper); PageInfoUserVO pageInfo new PageInfo(list);避坑提示确保XML中的${ew.sqlSegment}放在WHERE标签内参数名必须为ewWrapper的默认别名3.3 方案三改用selectList方法PageHelper.startPage(1, 10); ListUser users userMapper.selectList(wrapper); PageInfoUser pageInfo new PageInfo(users);局限性只能返回实体对象无法直接映射VO需要手动处理对象转换3.4 方案四二次内存分页应急方案// 关闭PageHelper分页 ListUserVO allData userMapper.selectVoList(wrapper); // 手动分页 int fromIndex (pageNum - 1) * pageSize; ListUserVO pageData allData.stream() .skip(fromIndex) .limit(pageSize) .collect(Collectors.toList());适用场景数据量小于1000条需要复杂的内存计算4. 性能对比测试通过JMH对10万级数据量进行基准测试单位ms方案平均耗时内存占用适用场景MP原生分页12035MB标准分页查询PageHelperXML14542MB需要复杂SQL的场景内存分页2100280MB小数据量复杂业务逻辑5. 生产环境配置建议5.1 混合使用时的配置要点Configuration public class MybatisConfig { // MyBatis-Plus插件 Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 分页插件必须放在首位 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 其他插件... return interceptor; } // PageHelper插件 Bean public PageInterceptor pageInterceptor() { return new PageInterceptor(); } }关键顺序确保MyBatis-Plus的PaginationInnerInterceptor最先加载PageInterceptor的order值要大于前者5.2 事务中的特殊处理在Transactional方法内混用两种分页时建议Transactional public void batchProcess() { // 方案1使用MP分页 PageUser page new Page(1, 100); userMapper.selectPage(page, wrapper); // 方案2需要PageHelper时开启新事务 TransactionTemplate transactionTemplate new TransactionTemplate(transactionManager); transactionTemplate.execute(status - { PageHelper.startPage(1, 10); return userMapper.selectByCustomSql(); }); }6. 常见问题排查指南6.1 分页失效检查清单确认插件加载顺序正确检查是否有多数据源配置冲突验证ThreadLocal是否被意外清除查看最终执行的SQL日志6.2 典型异常处理问题一Total始终为0// 原因MP分页插件未正确配置count查询 new PageUser(1, 10).setSearchCount(true); // 或者在wrapper中手动指定 wrapper.select(COUNT(1));问题二分页参数重复// 错误示例两种分页方式混用 PageHelper.startPage(1, 10); PageUser page new Page(1, 10); // 正确做法二选一7. 架构设计思考对于新项目建议的选型策略纯MyBatis-Plus项目直接使用其分页功能遗留系统改造采用方案二自定义XML需要特殊分页逻辑考虑实现自定义分页插件对于高频分页查询可扩展PageHelper的PageInfopublic class CustomPageInfoT extends PageInfoT { private String extraField; public CustomPageInfo(ListT list) { super(list); // 自定义扩展逻辑 } }我在实际项目中的经验是当分页需求简单时MyBatis-Plus原生分页完全够用遇到复杂报表查询时配合PageHelper的物理分页内存计算反而更灵活。关键是根据业务场景选择合适的工具而不是盲目追求统一。