怎么在Spring Boot中配置MyBatis的分页插件_PageHelper集成与SQL拦截

PageHelper 需用官方 starter（如 1.4.6/1.5.0+）并排除 MybatisAutoConfiguration；startPage() 必须紧邻 mapper 调用，避免 AOP 干扰；count 报错时可配 count(1) 或手动写 count 方法；返回前端须转 PageResult 等 DTO，禁用直接序列化 Page。

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<T> 工具方法，把 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<T> 是 List 子类，但含额外字段（pageNum、total 等），直接 JSON 序列化会暴露内部结构，且不同 Jackson 版本行为不一致 —— 有的序列化出空数组，有的抛 NoSerializerFoundException。

• 永远不要把 Page<T> 直接塞进 @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 不会自动继承

事情说清了就结束

Cutout.Pro抠图

AI批量抠图去背景

下载