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排序，示例代码：

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

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

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

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