SpringBoot集成PageHelper分页教程

本文深入剖析了Spring Boot集成PageHelper分页插件的常见陷阱与最佳实践，涵盖依赖冲突规避（推荐官方starter并排除MybatisAutoConfiguration）、startPage()调用时机的严格要求（必须紧邻mapper查询以保障ThreadLocal上下文不被AOP或事务中断）、count查询报错的多种解决方案（如配置count(1)、禁用自动count并手动实现统计方法），以及分页结果安全返回前端的关键规范（禁止直接序列化Page对象，必须封装为纯净DTO如PageResult）。内容直击生产环境高频问题，兼顾原理透彻性与落地可操作性，是开发者高效、稳定实现分页功能的实用指南。

PageHelper 依赖怎么加才不冲突 Spring Boot 2.3+ 默认用 HikariCP，而 PageHelper 5.x 对 MyBatis 3.4+ 兼容良好，但容易和 mybatis-spring-boot-starter 的自动配置打架。常见现象是分页失效、PageHelper.startPage() 调用后查出来还是全量数据。

• 必须显式排除 mybatis-spring-boot-starter 自带的 MybatisAutoConfiguration，否则它会抢先注册一个没插件的 SqlSessionFactory
• 推荐用 PageHelper 官方维护的 starter：pagehelper-spring-boot-starter，版本要对齐：Spring Boot 2.7.x 对应 pagehelper-spring-boot-starter 1.4.6，3.x 对应 1.5.0+
• 如果项目已手动配置 SqlSessionFactory，就别再引入 starter，改用原生方式注册 PageInterceptor，否则两个拦截器叠加导致 offset 错乱

PageHelper.startPage() 为什么在 service 层调用就失效 这不是 bug，是 MyBatis 插件机制决定的：PageHelper 本质靠 ThreadLocal 存当前分页参数，而 startPage() 只影响「紧接其后的第一个查询语句」。一旦中间有事务切面、异步调用、或被其他 AOP 干扰，ThreadLocal 就断了。

• 绝对不要在 controller 或 service 的非直接 DAO 调用前调用 startPage()，比如写成 PageHelper.startPage(1,10); return userService.list(); —— 这里 list() 内部可能跨方法、跨事务，ThreadLocal 已丢失
• 正确位置只该在 mapper 接口调用前一毫秒，最稳的是在 service 方法里紧挨着 mapper.selectXXX() 写，例如：

  PageHelper.startPage(1, 20);
  List<User> users = userMapper.selectAll(); // 必须紧跟这一行

• 更健壮的做法是封装一层 PageResult 工具方法，把 startPage 和 select 绑死在同一栈帧里

SQL 被拦截后 count 查询总出错：count(1) vs count(*) PageHelper 自动生成 count 查询时，默认用 count(*)，但某些数据库（如老版本 MySQL 5.6 + 带函数索引的表）或自定义 SQL（含 GROUP BY、HAVING、窗口函数）会导致 count 报错： ERROR: column "xxx" must appear in the GROUP BY clause or be used in an aggregate function

• 在 application.yml 中强制指定 count 方式：pagehelper.count-column: count(1)，比 count(*) 更宽松
• 如果 SQL 含复杂子查询或 CTE，干脆关掉自动 count：pagehelper.reasonable: false + pagehelper.support-methods-arguments: true，然后手动写两个 mapper 方法：selectXxxList 和 selectXxxCount，传参一致
• 注意：开启 support-methods-arguments 后，startPage 就不能用了，得改用带参数的 PageMethod.startPage(pageNum, pageSize)

PageHelper 分页结果怎么安全返回给前端PageHelper 返回的 Page 是 List 子类，但含额外字段（pageNum、total 等），直接 JSON 序列化会暴露内部结构，且不同 Jackson 版本行为不一致 —— 有的序列化出空数组，有的抛 NoSerializerFoundException。

• 永远不要把 Page 直接塞进 @ResponseBody，必须转成干净的 DTO，例如：

  Page<User> page = PageHelper.startPage(1, 10).doSelectPage(() -> userMapper.selectAll());
  PageResult<User> result = new PageResult<>(page.getList(), page.getTotal(), page.getPageNum(), page.getPageSize());

• 如果用 Lombok，别给 Page 加 @Data，它重写了 toString() 和 equals()，容易在日志或缓存中引发意外序列化
• 复杂点在于：PageHelper 的分页上下文是线程绑定的，如果用 CompletableFuture 异步查分页，必须手动传递 Page 实例，ThreadLocal 不会自动继承

事情说清了就结束

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。