Spring Boot 使用 PageHelper 分页异常：排序引发的“隐形坑”全解析

做Spring Boot项目开发的小伙伴，大概率都用过PageHelper做分页查询------毕竟它简洁高效，一行代码就能实现分页，之前项目里一直用得顺风顺水，从没出过错。

可就在昨天，分页突然"罢工"了，排查了大半天才找到根源，今天就把这个踩坑经历分享出来，帮大家避开这个隐形陷阱！

报错效果和核心代码如下（大家可以对照自己的项目排查）：

【核心代码】：就是最常规的PageHelper分页操作，仅新增了排序逻辑，代码如下：

一步步排查，锁定排序这个"罪魁祸首"

比较其他业务发现，只多了个排序操作，所以尝试去掉排序------奇迹发生了，分页总数恢复正常，total能正确获取到，分页功能也完全正常。这就基本确定：异常就是排序操作引发的。

通过Debug跟踪代码执行过程，重点查看分页插件的执行逻辑。发现了核心问题：新增排序后，分页插件并没有执行"查询总数"的SQL语句（也就是count查询）。

具体表现为：Debug到分页插件的核心逻辑时，负责查询总数的那一行代码（PageHelper内部的count查询逻辑）始终没有执行，直接跳过，导致total无法获取，最终异常。如图所示

深挖源码，找到底层原因：查阅了PageHelper的源码，重点分析了orderBy方法和beforeCount方法的执行逻辑。如图所示

最终发现：PageHelper的orderBy方法，在执行时会自动创建一个Page对象，而这个自动创建的Page对象，会导致PageHelper内部的beforeCount方法返回false---分页插件就会跳过count查询，自然就无法获取到分页总数了。

为什么排序会导致分页总数获取失败？

很多小伙伴可能还是有疑问：排序和分页总数，看似毫无关联，为什么会相互影响？

其实核心原因在于PageHelper的Page对象构建机制------PageHelper的分页功能，本质上是通过构建Page对象来实现的，而Page对象的构建有两种常见的方式，这也是本次异常的关键：

方式一：使用PageHelper.startPage(pageNum, pageSize)方法，手动开启分页，这种方式会主动构建一个"分页Page对象"，同时默认执行count查询，获取分页总数；
方式二：使用PageRowBounds对象，通过参数传递分页参数（pageNum、pageSize），这种方式也会触发分页，在拦截器中隐士构建Page对象。

而我们本次项目中，使用的是PageRowBounds方式 实现分页，但新增的PageHelper.orderBy方法，有一个"隐形操作"：它会优先创建一个"不分页的Page对象"，这个自动创建的Page对象，会让PageRowBounds构建Page逻辑失效。

解决方案，一次性搞定

通过这次踩坑，我们不仅找到了异常的根源，更掌握了PageHelper分页的核心细节，这里给大家整理了避坑要点和具体解决方案，以后遇到类似问题，直接对照解决即可：

1.核心避坑点：使用PageRowBounds方式分页时，禁止使用PageHelper.orderBy方法------orderBy会自动创建不分页的Page对象，让PageRowBounds的分页配置失效，导致count查询失效、总数异常。

2.正确排序方式（两种可选）：

① 放弃PageRowBounds，改用PageHelper.startPage方法分页，同时在startPage之后、查询之前执行orderBy排序，示例代码：

Java 复制代码

 // 正确写法：startPage + orderBy
PageHelper.startPage(pageNum, pageSize);
PageHelper.orderBy("create_time desc");

② 保留PageRowBounds分页，将排序逻辑写入Mapper接口的SQL语句中（推荐，更高效、更稳定），示例代码：

XML 复制代码

<select>
// Mapper接口SQL（新增order by）
select * from user where status = 1 order by create_time desc;
</select>

Java 复制代码

 // 代码中仅保留分页，无需额外排序
PageRowBounds pageRowBounds = new PageRowBounds(pageNum, pageSize);
List<User> userList = userMapper.selectUserList(pageRowBounds);

最后总结

其实这次异常，本质上是对PageHelper的底层逻辑了解不够深入------我们只知道orderBy能实现排序，却不知道它背后会自动创建Page对象，进而影响分页逻辑。很多技术踩坑，看似诡异，实则都是"细节疏忽"导致的。这里也补充几个关键注意事项，帮大家进一步避坑：

尽量避免混用PageHelper的多种分页方式（startPage和PageRowBounds不要同时使用）；
使用orderBy方法时，务必确认当前的分页方式，避免触发"自动创建不分页Page对象"的隐形逻辑；

希望这篇解析，能帮大家避开这个PageHelper的隐形陷阱，以后做分页+排序时，少走弯路、提高开发效率。如果大家还有其他PageHelper的使用问题，也可以在评论区交流，一起避坑、一起进步！