1. 为什么分页这件事值得单独拎出来讲做业务系统时间长了你会发现一个规律几乎所有列表页都逃不开分页而分页恰恰是最容易出问题、也最容易被忽视的地方。刚入行的同学写分页往往是在业务代码里手动拼limit和offset再写一条count语句看起来简单直接但一旦查询条件变复杂、SQL 变长、多表关联变多这种手写方式就会变成维护噩梦。PageHelper 这个 MyBatis 扩展插件就是来解决这个痛点的——它让你在几乎不改动原有查询逻辑的前提下自动完成分页查询和总数统计。我接触 PageHelper 大概是在做第一个后台管理系统的时候当时一个订单列表要支持十几个筛选条件手写分页写到怀疑人生。后来换成 PageHelper一行PageHelper.startPage(pageNum, pageSize)就搞定那种感觉确实很爽。但用得越久踩的坑也越多线程安全问题、count查询慢、分页失效、嵌套查询结果不对……这些问题文档里往往一笔带过真正踩过才知道疼。这篇内容我打算把 PageHelper 从原理到实操完整梳理一遍包括它到底怎么工作的、Spring Boot 里怎么集成、常见配置项怎么选、count查询慢怎么优化、以及那些只有踩过坑才知道的注意事项。适合正在用 MyBatis 做业务开发的同学也适合准备面试、想搞清楚分页底层机制的朋友。看完你应该能独立把 PageHelper 用稳、用对而不是停留在“能跑就行”的阶段。2. PageHelper 的核心原理与设计思路拆解2.1 它本质上是一个 MyBatis 拦截器很多人用 PageHelper 用了很久却说不清它到底是怎么把分页塞进 SQL 里的。要理解这一点得先知道 MyBatis 的插件机制。MyBatis 允许你通过Interceptor接口拦截四大核心对象的方法调用Executor、StatementHandler、ParameterHandler、ResultSetHandler。PageHelper 选择拦截的是Executor的query方法因为分页本质上是在查询执行前对 SQL 做改写。具体流程是这样的当你调用PageHelper.startPage(pageNum, pageSize)时它会把分页参数放进当前线程的ThreadLocal里。等到 MyBatis 真正执行查询、走到被拦截的Executor.query时PageHelper 从ThreadLocal里取出参数判断这次查询需不需要分页。如果需要它就先根据原 SQL 生成一条count语句查总数再对原 SQL 拼接limit子句最后把结果封装成一个Page对象返回。这里有个关键点分页参数是存在 ThreadLocal 里的这意味着startPage和紧接着的那一次查询必须在同一个线程里而且中间不能插入其他查询。这是后面很多“分页失效”问题的根源先记住这一点。2.2 为什么用拦截器而不是手写分页你可能会问既然拦截器这么绕为什么不直接在业务层手写分页我总结了几个实际开发中的理由。第一是代码侵入性低。手写分页意味着每个查询方法都要多写一条countSQL还要处理limit参数拼接。一个系统几十个列表页重复代码量惊人。PageHelper 把这些逻辑收敛到插件里业务代码只关心查询条件本身。第二是方言适配。不同数据库的分页语法不一样MySQL 用limitOracle 用rownumSQL Server 用top或offset fetch。PageHelper 内置了多种方言的Dialect实现能根据数据库类型自动生成对应的分页 SQL。如果你的系统要兼容多种数据库这个价值就体现出来了。第三是结果封装统一。PageHelper 返回的PageInfo对象里包含了总记录数、总页数、当前页、每页条数、是否为第一页/最后一页等字段前端直接拿来用就行不用自己算。当然拦截器方案也有代价最典型的就是count查询的性能问题以及 ThreadLocal 带来的隐式依赖。这些后面会详细讲。2.3 核心类之间的关系理解 PageHelper 的类结构对排查问题很有帮助。核心的几个类是这样的PageHelper对外暴露的工具类startPage方法就在这里负责把参数放进 ThreadLocal。PageInterceptor真正的拦截器实现实现Interceptor接口负责拦截Executor.query。Page继承自ArrayList既是一个分页参数载体也是查询结果的容器。PageInfo对Page的进一步封装提供更友好的分页元信息。SqlUtil和Dialect负责 SQL 改写和方言适配。调用链大致是PageHelper.startPage→ 参数存入 ThreadLocal →PageInterceptor.intercept拦截 → 生成 count SQL 并执行 → 改写原 SQL 加 limit → 执行查询 → 封装结果 → 清理 ThreadLocal。注意PageHelper 在查询结束后会调用clearPage清理 ThreadLocal但如果查询过程中抛异常或者你startPage之后没有执行查询ThreadLocal 里的参数可能残留导致下一次查询被意外分页。这是很隐蔽的 bug后面会专门讲。3. Spring Boot 集成 PageHelper 的完整实操3.1 依赖引入与版本选择在 Spring Boot 项目里集成 PageHelper最省事的方式是用 starter。Maven 依赖大概是这样dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.7/version /dependency版本选择上有个经验starter 版本要和你的 Spring Boot 版本大致匹配。1.4.x 系列适配 Spring Boot 2.x如果你用的是 Spring Boot 3.x需要选 2.x 系列的 starter因为 Spring Boot 3 把底层的一些依赖升级了老版本 starter 可能会有兼容问题。我见过有同学在 Spring Boot 3 项目里硬塞 1.4.x结果启动就报NoClassDefFoundError排查半天。另外要注意引入 starter 之后不要再单独引入pagehelper核心包starter 已经包含了重复引入容易造成版本冲突。如果你是非 Spring Boot 项目那就直接引pagehelper核心包然后手动配置拦截器。3.2 application.yml 关键配置项starter 的好处是配置可以写在application.yml里常用的配置项如下pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql page-size-zero: false逐项说一下我的理解helper-dialect指定方言。虽然 PageHelper 能自动检测数据库类型但显式指定更稳妥尤其是在多数据源场景下自动检测可能出错。常见值有mysql、oracle、postgresql、sqlserver等。reasonable是“合理化分页”这个配置很实用。开启后如果pageNum小于 1会查第一页如果pageNum大于总页数会查最后一页。不开的话传个负数或者超大页码可能返回空结果甚至报错。生产环境建议开启。support-methods-arguments允许你通过 Mapper 方法的参数来传递分页信息不用显式调startPage。这个功能用好了能简化代码但也会让分页变得“隐式”团队协作时容易让人困惑看情况用。params里的countcountSql是配合support-methods-arguments用的指定哪个参数是 count 查询的标识。page-size-zero默认 false意思是当pageSize为 0 时查全部数据不分页。这个行为有点危险如果前端传了 0可能一次性把整张表拉出来。我一般会保持 false然后在业务层校验pageSize的合法范围。3.3 一个完整的分页查询示例光说配置不够直观直接上一个能跑的完整例子。假设有一个用户表我们要按条件分页查询。先看实体类和 Mapperpublic class User { private Long id; private String name; private Integer age; private String email; // getter setter 省略 }Mapper public interface UserMapper { ListUser selectByCondition(Param(name) String name, Param(age) Integer age); }对应的 XMLselect idselectByCondition resultTypecom.example.entity.User SELECT id, name, age, email FROM user where if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %) /if if testage ! null AND age #{age} /if /where ORDER BY id DESC /selectService 层调用Service public class UserService { Autowired private UserMapper userMapper; public PageInfoUser queryByPage(String name, Integer age, int pageNum, int pageSize) { // 关键startPage 必须紧挨着查询方法 PageHelper.startPage(pageNum, pageSize); ListUser list userMapper.selectByCondition(name, age); return new PageInfo(list); } }Controller 层RestController RequestMapping(/user) public class UserController { Autowired private UserService userService; GetMapping(/list) public PageInfoUser list(RequestParam(defaultValue 1) int pageNum, RequestParam(defaultValue 10) int pageSize, RequestParam(required false) String name, RequestParam(required false) Integer age) { return userService.queryByPage(name, age, pageNum, pageSize); } }这段代码跑起来PageHelper 会自动帮你做两件事先执行一条SELECT count(0) FROM user WHERE ...查总数再执行带LIMIT的查询拿当前页数据。返回的PageInfo里total、pages、pageNum、pageSize、list都齐了前端直接渲染分页组件。3.4 startPage 的几种重载与使用场景PageHelper.startPage有好几个重载常用的有// 最常用页码 每页条数 PageHelper.startPage(int pageNum, int pageSize); // 带排序第三个参数是排序字段注意有 SQL 注入风险 PageHelper.startPage(int pageNum, int pageSize, String orderBy); // 带是否统计总数false 表示不查 count适合已知不需要总数的场景 PageHelper.startPage(int pageNum, int pageSize, boolean count); // 带合理化分页覆盖全局配置 PageHelper.startPage(int pageNum, int pageSize, boolean count, boolean reasonable);关于orderBy参数我要特别提醒不要直接把前端传来的排序字段拼进去。PageHelper 内部对orderBy做了简单的 SQL 注入过滤但过滤规则不是万能的。稳妥的做法是在业务层做白名单校验只允许特定的字段参与排序。count参数为 false 的场景也值得说。有些列表页前端不需要显示总数只需要“下一页”按钮这时候关掉 count 查询能省一次数据库交互性能提升明显。我做过一个日志查询页面数据量上千万关掉 count 之后响应时间从 3 秒降到 300 毫秒。4. count 查询慢的根因分析与优化实战4.1 为什么 count 会慢这是 PageHelper 被吐槽最多的地方也是面试高频问题。要搞清楚为什么慢得先看 PageHelper 生成的 count SQL 长什么样。假设你的原 SQL 是SELECT id, name, age, email FROM user u LEFT JOIN department d ON u.dept_id d.id WHERE u.status 1 AND d.name LIKE %技术% ORDER BY u.id DESCPageHelper 默认会把它改写成SELECT count(0) FROM user u LEFT JOIN department d ON u.dept_id d.id WHERE u.status 1 AND d.name LIKE %技术%注意它去掉了 ORDER BY但保留了所有 JOIN。问题就出在这里如果 JOIN 的表很大或者 JOIN 条件没有走索引count 查询会非常慢。更糟的是有些场景下 JOIN 会产生笛卡尔积式的行数膨胀count 出来的数字可能都不对。还有一种情况是WHERE条件里有LIKE %xxx%这种前置模糊匹配索引直接失效count 全表扫描数据量一大就卡死。4.2 优化思路一手写 count SQLPageHelper 提供了自定义 count 查询的入口。你可以在 Mapper 里额外写一个 count 方法然后在startPage时指定用哪个 count 查询。Mapper public interface UserMapper { ListUser selectByCondition(Param(name) String name, Param(age) Integer age); long countByCondition(Param(name) String name, Param(age) Integer age); }XML 里select idcountByCondition resultTypelong SELECT count(0) FROM user where if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %) /if if testage ! null AND age #{age} /if /where /select调用时用PageHelper.startPage的重载把 count 方法名传进去PageHelper.startPage(pageNum, pageSize, countByCondition); ListUser list userMapper.selectByCondition(name, age);这样 PageHelper 就不会自己生成 count SQL而是调用你指定的方法。你可以针对 count 做专门的优化比如去掉不必要的 JOIN、只查主表、利用覆盖索引等。4.3 优化思路二用近似值替代精确 count如果业务上能接受“总数不精确”比如显示“约 1000 条”那可以用一些取巧的办法。MySQL 的EXPLAIN结果里有个rows字段是优化器估算的行数虽然不准但速度极快。你可以写一个 count 方法用EXPLAIN拿估算值EXPLAIN SELECT id FROM user WHERE status 1然后解析结果里的rows。这种方式适合数据量极大、对总数精度要求不高的场景比如后台的日志列表、监控数据列表。还有一种做法是缓存总数。如果数据变化不频繁可以把 count 结果缓存起来比如用 Redis 存 5 分钟。用户翻页时直接用缓存的总数只有缓存过期才真正查一次数据库。这个方案在商品列表、文章列表这类读多写少的场景很有效。4.4 优化思路三避免不必要的 count前面提过PageHelper.startPage(pageNum, pageSize, false)可以关闭 count 查询。什么时候适合关前端是“无限滚动”加载不需要知道总数。只需要“下一页”按钮不需要页码跳转。数据量极大count 成本远高于查询本身。我个人的经验是列表页如果超过 100 万行优先考虑关掉 count 或者用近似值否则用户体验会被 count 拖垮。4.5 一个真实的优化案例之前做过一个订单查询页面数据量 800 万左右查询条件涉及订单表、用户表、商品表三表关联。上线后发现列表加载要 5 秒以上慢查询日志里全是 count 语句。排查过程是这样的先看 count SQL发现它保留了三个表的 JOIN而实际上用户表和商品表只是为了显示名称对筛选条件没有贡献。于是手写了一个 count 方法只查订单表把用户和商品的筛选条件通过子查询或者冗余字段解决。改完之后 count 从 4 秒降到 200 毫秒。后来又加了一层 Redis 缓存把 count 结果缓存 3 分钟进一步把大部分请求的响应时间压到 50 毫秒以内。这个案例说明count 优化的核心是减少参与 count 的数据量能不加 JOIN 就不加能用索引就用索引。5. 那些文档不会告诉你的坑与排查技巧5.1 分页失效的几种典型场景分页失效是 PageHelper 最常见的问题表现是查询返回了全部数据没有分页。我总结了几种原因第一种startPage 和查询方法之间插入了其他查询。因为分页参数存在 ThreadLocal 里只对紧接着的第一次查询生效。如果你这样写PageHelper.startPage(pageNum, pageSize); User user userMapper.selectById(1L); // 这次查询被分页了 ListUser list userMapper.selectByCondition(name, age); // 这次没有分页结果就是selectById被莫名其妙分页而真正想分页的selectByCondition反而没分页。这种 bug 很隐蔽因为selectById返回单条分页了也看不出来。第二种多数据源场景下方言识别错误。如果项目里配了多个数据源PageHelper 自动检测方言可能识别成错误的数据库类型导致生成的 limit 语法不对。解决办法是显式配置helper-dialect或者用PageHelper.startPage时指定方言。第三种查询方法被 AOP 代理或者异步执行。如果查询方法跑在另一个线程里ThreadLocal 取不到分页参数分页自然失效。异步查询场景要特别注意。5.2 ThreadLocal 残留导致的分页错乱这个坑比失效更恶心因为它会导致不该分页的查询被分页。场景是这样的PageHelper.startPage(pageNum, pageSize); // 中间因为某个条件判断直接 return 了没有执行查询 if (condition) { return Collections.emptyList(); } ListUser list userMapper.selectByCondition(name, age);如果condition为 true 直接返回ThreadLocal 里的分页参数没有被清理。下一次请求进来如果恰好是同一个线程线程池复用这个残留的参数就会作用到下一次查询上导致分页错乱。解决办法有两个一是确保 startPage 之后一定执行查询二是在 finally 里手动调用PageHelper.clearPage()。我现在的习惯是只要用了 startPage就在 try-finally 里包一层虽然啰嗦但安心。5.3 PageInfo 和 Page 的区别与选择很多人分不清Page和PageInfo。简单说Page是ArrayList的子类查询返回的List实际上就是Page类型它带有total、pageNum、pageSize等属性。PageInfo是对Page的封装额外提供了isFirstPage、isLastPage、hasNextPage、navigatePages等更友好的字段。选择上如果前端只需要总数和当前页数据用Page就够了。如果需要完整的分页导航信息比如显示“上一页 1 2 3 4 5 下一页”用PageInfo更方便。PageInfo的构造函数接收一个List内部会判断是不是Page类型如果是就提取分页信息如果不是就当作普通列表处理total 等于 list 大小。注意如果你在startPage之后对返回的 list 做了过滤、转换比如 stream 操作生成新 list再传给PageInfo分页信息会丢失因为新 list 不是Page类型了。正确做法是先构造PageInfo再做数据转换。5.4 常见问题速查表问题现象可能原因排查方向解决办法查询返回全部数据startPage 未生效检查 startPage 与查询是否紧邻调整代码顺序不该分页的查询被分页ThreadLocal 残留检查是否有提前 returnfinally 中 clearPagecount 查询特别慢JOIN 过多或索引失效看慢查询日志手写 count SQL分页页码越界返回空reasonable 未开启检查配置开启 reasonable多数据源分页语法错误方言识别错误检查数据源配置显式指定 dialectPageInfo 的 total 不对list 被转换过检查是否 stream 操作先构造 PageInfo5.5 几个实操心得第一startPage 尽量写在 Service 层不要写在 Controller。Controller 只负责参数接收和结果返回分页逻辑属于业务范畴放 Service 层更合理也方便复用。第二pageSize 一定要做上限校验。我见过前端传pageSize100000直接把数据库打挂的案例。一般限制在 100 以内比较稳妥特殊场景可以放宽到 500。第三排序字段用白名单。前面提过orderBy的注入风险实际项目中我会维护一个允许排序的字段集合前端传的字段不在集合里就用默认排序。第四分页查询尽量走覆盖索引。如果查询字段都能被索引覆盖数据库不用回表速度会快很多。这个属于 SQL 优化范畴但对分页性能影响很大。6. 面试中关于 PageHelper 的高频问题拆解6.1 PageHelper 的分页原理是什么这是最基础的面试题。回答要点PageHelper 基于 MyBatis 的 Interceptor 机制拦截Executor.query方法。调用startPage时把分页参数存入 ThreadLocal拦截器在执行查询前从 ThreadLocal 取出参数先生成并执行 count SQL 查总数再改写原 SQL 拼接 limit 子句最后把结果封装成 Page 对象返回并清理 ThreadLocal。如果能补充“为什么用 ThreadLocal”就更好了因为分页参数需要在不修改方法签名的前提下传递给拦截器ThreadLocal 是最轻量的方案但代价是隐式依赖和线程安全问题。6.2 PageHelper 的 count 查询可以优化吗可以。三个方向手写 count SQL 去掉不必要的 JOIN用近似值或缓存替代精确 count关闭 count 查询startPage第三个参数传 false。面试时如果能结合具体案例讲比如“我之前做过一个 800 万数据的订单列表通过手写 count 把响应时间从 4 秒降到 200 毫秒”会加分很多。6.3 PageHelper 和 MyBatis-Plus 的分页有什么区别MyBatis-Plus 的分页是基于它自己的IPage接口和PaginationInnerInterceptor实现的用法上是传一个Page对象作为方法参数而不是用 ThreadLocal。相比之下MyBatis-Plus 的分页更“显式”不容易出现 ThreadLocal 残留问题但侵入性稍高方法签名要改。PageHelper 胜在无侵入适合已有项目快速接入。两者没有绝对优劣看项目情况选。6.4 分页查询的深分页问题怎么解决深分页指的是LIMIT 1000000, 10这种偏移量很大时数据库要扫描并丢弃前 100 万行效率极低。解决办法有几种用游标分页记录上一页最后一条的 id下一页用WHERE id lastId LIMIT 10用子查询先定位 id 再关联或者限制用户只能翻到前 N 页。PageHelper 本身不解决深分页需要业务层配合。7. 一些延伸思考与个人建议PageHelper 这个组件用起来简单但要用好需要理解它的边界。我的建议是把它当成一个提效工具而不是万能方案。简单列表页直接用它没问题但数据量大、查询复杂的场景一定要针对 count 做优化必要时手写分页逻辑。另外新项目如果还没选型可以对比一下 MyBatis-Plus 的分页。它的显式传参方式在团队协作和问题排查上更友好而且 MyBatis-Plus 本身提供了很多 CRUD 的便利。老项目已经在用 PageHelper 的也没必要迁移把 count 优化和 ThreadLocal 清理做好就行。最后分享一个小技巧如果你在本地调试时想看到 PageHelper 实际生成的 SQL可以把 MyBatis 的日志级别调到 DEBUG配置logging.level.com.example.mapperdebug这样控制台会打印出 count SQL 和分页 SQL排查问题非常方便。我每次遇到分页结果不对第一件事就是打开日志看实际执行的 SQL十有八九能直接定位问题。