当前位置：首页 > news >正文

PageHelper分页失效排查指南：从‘总页数总是第一页’到精准定位

news 2026/5/11 12:22:56

1. 为什么PageHelper分页总显示第一页？

最近在项目里用PageHelper做分页时，发现一个奇怪现象：明明传了正确的页码参数，但返回结果总是显示第一页的数据。这个问题困扰了我整整两天，后来才发现是配置上踩了坑。今天我就把排查过程完整分享出来，帮你避开这些"雷区"。

PageHelper作为MyBatis最常用的分页插件，原理是通过拦截SQL语句自动添加LIMIT子句。但实际使用中，很多开发者会遇到分页失效的情况，常见表现有：

返回的PageInfo对象中total总记录数正确，但数据列表始终是第一页
分页参数pageNum和pageSize明明传了值，但SQL执行时没有limit条件
控制台打印的SQL语句中看不到分页参数

2. 依赖配置检查：从源头排除问题

2.1 依赖版本冲突排查

我遇到的第一个坑就是依赖冲突。现在SpringBoot项目推荐直接使用starter包：

<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper-spring-boot-starter</artifactId> <version>1.4.3</version> </dependency>

老项目中常见的错误配置是只引入了核心包：

<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper</artifactId> <version>5.3.2</version> </dependency>

这样会导致自动配置失效，必须手动注入拦截器。建议用mvn dependency:tree检查依赖树，确保没有多个版本的pagehelper共存。

2.2 自动配置验证

SpringBoot环境下，正确的配置应该能在启动日志看到这行提示：

PageHelperAutoConfiguration auto configured

如果没有看到，可能是自动配置被排除掉了。检查启动类上的注解：

@SpringBootApplication(exclude = { // 确保没有排除PageHelperAutoConfiguration })

3. 拦截器加载机制剖析

3.1 手动配置的正确姿势

在非SpringBoot环境或需要自定义配置时，必须手动配置拦截器。常见错误是只配置了插件但没设置属性：

@Bean public PageInterceptor pageInterceptor() { PageInterceptor interceptor = new PageInterceptor(); Properties properties = new Properties(); // 关键配置项 properties.setProperty("helperDialect", "mysql"); properties.setProperty("reasonable", "true"); properties.setProperty("supportMethodsArguments", "true"); interceptor.setProperties(properties); return interceptor; }

特别注意：如果使用多数据源，需要在每个SqlSessionFactory中都添加拦截器。

3.2 配置文件方式

传统MyBatis项目可以在mybatis-config.xml中配置：

<plugins> <plugin interceptor="com.github.pagehelper.PageInterceptor"> <property name="dialect" value="mysql"/> <property name="reasonable" value="true"/> </plugin> </plugins>

但要注意文件路径必须能被正确加载，建议在application.yml中显式指定：

mybatis: config-location: classpath:mybatis-config.xml

4. SQL执行顺序陷阱

4.1 分页语句位置问题

PageHelper有个重要特性：startPage()只对紧接着的第一个查询生效。比如这样写就会失效：

PageHelper.startPage(1, 10); // 这里有个无关操作 List<User> users = userMapper.selectAll(); // 这个查询不会分页

正确的写法应该是：

PageHelper.startPage(1, 10); List<User> users = userMapper.selectAll(); // 这个查询会被分页

4.2 多线程环境下的坑

在异步方法中使用PageHelper时，分页参数是通过ThreadLocal传递的。如果遇到这种情况：

PageHelper.startPage(1, 10); CompletableFuture.runAsync(() -> { userMapper.selectAll(); // 这里拿不到分页参数 });

解决方案是先在主线程执行查询：

PageHelper.startPage(1, 10); List<User> users = userMapper.selectAll(); CompletableFuture.runAsync(() -> { processUsers(users); // 使用已分页的结果 });

5. 数据库方言配置要点

5.1 自动检测失效场景

PageHelper支持自动检测数据库类型，但在以下情况会失效：

使用自定义数据源时
多数据源环境下
某些连接池返回的Connection元信息不全

这时需要显式指定方言：

pagehelper.helper-dialect=mysql pagehelper.reasonable=true

5.2 特殊数据库的配置

对于达梦、人大金仓等国产数据库，可能需要自定义方言：

public class KingbaseDialect extends MySqlDialect { @Override public String getPageSql(String sql, Page page) { // 自定义分页语法 } }

然后在配置中指定：

pagehelper.helper-dialect=com.yourpackage.KingbaseDialect

6. 实战调试技巧

6.1 日志级别设置

开启DEBUG日志可以查看分页过程：

logging.level.com.github.pagehelper=debug

正常会看到类似日志：

DEBUG [main] - SQL: select * from user LIMIT ? DEBUG [main] - Parameters: 10(Integer)

6.2 使用PageHelper.doPage

如果怀疑分页没生效，可以用这个方法强制分页：

List<User> users = userMapper.selectAll(); PageInfo<User> pageInfo = PageHelper.doPage(1, 10, () -> users);

这个方法会绕过自动拦截机制，直接对内存列表分页。

7. 高频问题解决方案

7.1 分页后total不对

如果发现PageInfo中的total比实际数据量大很多，可能是count查询出了问题。可以这样优化：

PageHelper.startPage(1, 10, true); // 第三个参数表示是否执行count查询 PageHelper.count(() -> userMapper.selectAll()); // 手动指定count方法

7.2 特殊SQL的处理

对于包含UNION、WITH等复杂语法的SQL，可能需要关闭自动count：

PageHelper.startPage(1, 10, false); // 不执行count查询 List<User> users = userMapper.selectComplexQuery(); PageInfo<User> pageInfo = new PageInfo<>(users); pageInfo.setTotal(manualCount); // 手动设置总数