1. 为什么我们需要MyBatis分页插件在Web应用开发中分页查询是最常见的需求之一。想象一下当你的电商网站有上百万商品时不可能一次性把所有商品都加载到页面上。传统的分页实现方式通常有两种第一种是在SQL中直接使用LIMIT和OFFSETMySQL或ROWNUMOracle等数据库特定的语法。这种方式虽然直接但存在几个明显问题不同数据库语法差异大代码难以移植需要手动计算分页参数分页逻辑与业务代码耦合度高第二种是在内存中分页即先查询所有数据再用Java代码切片。这种方式在数据量大时简直是性能灾难我曾经见过一个新手开发者用这种方式处理10万条数据直接导致OOM。PageHelper的出现完美解决了这些问题。它通过MyBatis拦截器机制自动将简单的分页查询转换为数据库特定的物理分页语句。你只需要在查询前设置分页参数后续的SQL转换、参数计算等脏活累活都由它来完成。2. Spring Boot集成PageHelper全攻略2.1 依赖配置的正确姿势在Spring Boot项目中集成PageHelper非常简单官方提供了专门的starter。但根据我的经验很多人在这里会踩坑。下面是经过生产验证的配置方式dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version /dependency注意点不要同时引入pagehelper和starter这会导致冲突生产环境建议锁定版本号避免自动升级带来意外对于Spring Boot 2.7建议使用1.4.x版本2.2 配置参数详解在application.yml中我通常使用以下优化过的配置pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql auto-runtime-dialect: true关键参数解析reasonable开启分页合理化当pageNum1时返回第一页pageNum总页数时返回最后一页auto-runtime-dialect支持多数据源自动识别方言params将RowBounds参数映射为Page参数警告在Oracle环境下必须关闭reasonable否则会导致ROWNUM分页异常2.3 与MyBatis的整合要点很多同学反映配置后不生效通常是MyBatis配置顺序问题。正确的配置类应该这样写Configuration AutoConfigureAfter(MybatisAutoConfiguration.class) public class PageHelperConfig { Bean public PageInterceptor pageInterceptor() { return new PageInterceptor(); } }关键点必须确保在MyBatis配置完成后初始化不要手动创建SqlSessionFactoryBean让Spring Boot自动配置3. PageHelper的实战技巧3.1 基础分页查询标准的使用姿势是这样的public PageInfoUser findUsers(int pageNum, int pageSize) { PageHelper.startPage(pageNum, pageSize); ListUser users userMapper.selectAll(); return new PageInfo(users); }注意PageHelper.startPage()必须紧挨着Mapper查询中间不能有其它查询否则会被错误拦截返回PageInfo对象包含完整分页信息3.2 复杂查询分页处理对于多表关联查询PageHelper也能完美支持public PageInfoOrderVO findOrderWithUser(int pageNum, int pageSize) { PageHelper.startPage(pageNum, pageSize); ListOrderVO orders orderMapper.selectWithUser(); return new PageInfo(orders); }原理是PageHelper会自动改写SQL在外层包裹分页查询。但要注意关联查询不要使用select *只查询需要的字段复杂的嵌套查询可能需要手动优化SQL3.3 分页结果封装技巧PageInfo对象提供了丰富的分页信息// 前端常用的分页响应结构 public class PageResultT { private int pageNum; private int pageSize; private long total; private ListT list; public static T PageResultT of(PageInfoT pageInfo) { PageResultT result new PageResult(); result.setPageNum(pageInfo.getPageNum()); result.setPageSize(pageInfo.getPageSize()); result.setTotal(pageInfo.getTotal()); result.setList(pageInfo.getList()); return result; } }4. 高级特性与性能优化4.1 多数据源支持在微服务架构下一个服务可能连接多个数据库。PageHelper通过以下配置支持pagehelper: auto-runtime-dialect: true dialect-alias: oracleoracle9i;db2db2然后在代码中动态指定PageHelper.startPage(1, 10).usingDialect(oracle); ListUser users userMapper.selectAll();4.2 大数据量分页优化当处理百万级数据时深分页如第1000页性能会急剧下降。解决方案使用上一页/下一页代替直接跳页如果必须支持跳页采用子查询优化SELECT * FROM table WHERE id (SELECT id FROM table ORDER BY id LIMIT 10000, 1) LIMIT 10PageHelper支持这种优化模式PageHelper.startPage(1, 10, false).setOrderBy(id desc);4.3 与MyBatis-Plus的对比很多同学纠结用PageHelper还是MyBatis-Plus的分页特性PageHelperMyBatis-Plus使用简便性⭐⭐⭐⭐⭐⭐⭐⭐⭐功能丰富度⭐⭐⭐⭐⭐⭐⭐⭐⭐多数据库支持⭐⭐⭐⭐⭐⭐⭐⭐性能⭐⭐⭐⭐⭐⭐⭐社区活跃度⭐⭐⭐⭐⭐⭐⭐⭐⭐选择建议简单项目用MyBatis-Plus内置分页复杂项目、多数据源场景用PageHelper5. 生产环境踩坑记录5.1 线程安全问题最常见的错误是在Service层使用成员变量保存分页参数// 错误示例 private int pageNum; public void setPageNum(int pageNum) { this.pageNum pageNum; } public ListUser findUsers() { PageHelper.startPage(pageNum, 10); // 线程不安全 return userMapper.selectAll(); }正确做法是每次都在方法内部设置参数。5.2 分页失效场景以下情况会导致分页不生效在startPage()和Mapper调用之间有其他查询使用了二级缓存且命中缓存方法内部捕获了异常导致拦截器未执行5.3 性能监控建议建议在拦截器中添加监控逻辑public class MonitorPageInterceptor extends PageInterceptor { Override public Object intercept(Invocation invocation) throws Throwable { long start System.currentTimeMillis(); try { return super.intercept(invocation); } finally { long cost System.currentTimeMillis() - start; Metrics.record(pageQuery, cost); } } }6. 最佳实践总结经过多个项目的实战检验我总结出以下黄金法则保持简单不要在分页查询中添加复杂逻辑尽早过滤在SQL层面做好数据过滤不要查出来再处理监控告警对深分页查询pageNum100添加监控统一返回全项目统一使用PageInfo或自定义的PageResult测试覆盖特别要测试边界情况第一页、最后一页、超出范围等最后分享一个性能优化技巧对于不会变的分页数据如商品列表可以结合Redis缓存分页结果设置合理的过期时间。我在一个电商项目中采用这种方案QPS从200提升到了2000。