PageHelper失效是开发中最常见的问题之一。结合你之前的代码场景Service 中先查数据做补充再返回列表我整理了一份完整的失效场景清单和解决方案。一、最常见失效场景 TOP 51.startPage后没有立即执行 Mapper 查询java// ❌ 错误 PageHelper.startPage(1, 10); // 这里插入了其他操作日志、校验、缓存查询等 log.info(开始查询); ListUser list userMapper.selectList(); // ← 分页可能被跳过原因startPage只对紧接着的第一次查询生效。如果中间执行了任何select操作分页参数就被消耗了。✅ 正确写法java// ✅ 正确 PageHelper.startPage(1, 10); ListUser list userMapper.selectList(); // 立即查询 // 查询后再做其他处理2. 同一个方法中调用了多个 Mapper 查询java// ❌ 错误 PageHelper.startPage(1, 10); User user userMapper.selectById(1L); // ← 分页被这个查询消耗了 ListOrder orders orderMapper.selectList(); // ← 这个查询没有分页原因分页参数只绑定到第一次 Mapper 查询。✅ 正确写法java// ✅ 方式一分开两个方法 public void query() { // 查询用户不分页 User user userMapper.selectById(1L); // 分页查询订单 PageHelper.startPage(1, 10); ListOrder orders orderMapper.selectList(); } // ✅ 方式二使用 PageHelper 的 OrderBy 单独控制 PageHelper.startPage(1, 10, create_time DESC); ListOrder orders orderMapper.selectList();3. 方法内部有多个startPage调用java// ❌ 错误 PageHelper.startPage(1, 10); PageHelper.startPage(1, 20); // ← 覆盖了前一个 ListUser list userMapper.selectList(); // 结果pageSize20前一个被覆盖✅ 正确写法只调用一次startPage。4. 在循环中调用startPagejava// ❌ 错误 for (Long id : ids) { PageHelper.startPage(1, 10); ListOrder orders orderMapper.selectByUserId(id); // 分页上下文在循环中混乱 }✅ 正确写法将分页逻辑抽取为独立方法或使用PageHelper.clearPage()手动清理。5. 在已有事务的方法中使用startPagejava// ❌ 错误 Transactional public void queryWithTx() { PageHelper.startPage(1, 10); ListUser list userMapper.selectList(); // 事务中其他操作... }原因事务绑定连接后分页拦截器可能无法正常工作。这是多数据源 事务场景下的常见问题。✅ 正确写法java// ✅ 方式一将分页查询放在事务外 public void queryWithTx() { // 1. 分页查询无事务 PageHelper.startPage(1, 10); ListUser list userMapper.selectList(); // 2. 事务内操作 updateWithTx(list); } Transactional public void updateWithTx(ListUser list) { // 更新逻辑 }二、配置类失效场景6. 方言配置错误或未配置yaml# ❌ 错误方言不匹配 pagehelper: helper-dialect: oracle # 但实际是 MySQL # ✅ 正确自动识别或明确指定 pagehelper: helper-dialect: mysql验证方法开启 DEBUG 日志查看启动时打印的方言信息。7. 拦截器配置缺失非 Spring Boot 项目在非 Spring Boot 项目中需要在 MyBatis 配置文件中显式配置PageInterceptorxml!-- mybatis-config.xml -- plugins plugin interceptorcom.github.pagehelper.PageInterceptor property namehelperDialect valuemysql/ property namereasonable valuetrue/ /plugin /plugins三、数据源相关失效场景8. 多数据源 单 EntityManagerFactory 场景这种情况比较复杂结合你之前的场景分析javaDS(feature) public void query() { PageHelper.startPage(1, 10); ListVehicleBase list repository.listByVinCodes(vinCodes); // 分页可能失效 }原因分页拦截器依赖 MyBatis 的SqlSession多数据源切换时可能使用了错误的 Session 或连接。✅ 解决方案java// 方案一确保在同一个数据源上下文中完成分页 DS(master) public PageInfoVehicleBase query() { PageHelper.startPage(1, 10); ListVehicleBase list repository.listByVinCodes(vinCodes); return new PageInfo(list); } // 方案二如果必须切换数据源先获取数据再在 Java 层分页四、PageHelper 不生效的快速排查清单排查项检查方式startPage是否紧挨着 Mapper 查询检查两者之间是否有其他select操作是否在循环中使用检查代码中是否有循环调用startPage是否在事务中使用检查方法或类上是否有Transactional配置方言是否正确检查application.yml中的helper-dialect是否有多个分页插件冲突检查是否同时引入了PageHelper和MyBatis-Plus的分页SQL 是否有FOR UPDATEPageHelper不支持包含FOR UPDATE的 SQLreasonable是否导致意外修正检查reasonable: true时页码超出是否被修正为第 1 页日志中是否出现分页 SQL开启logging.level.com.github.pagehelper: DEBUG五、调试技巧开启 DEBUG 日志yamllogging: level: com.github.pagehelper: DEBUG org.mybatis: DEBUG启动后会在日志中看到textDEBUG - 执行分页查询: SELECT * FROM user WHERE status 1 DEBUG - 分页参数: pageNum1, pageSize10 DEBUG - 生成分页 SQL: SELECT * FROM user WHERE status 1 LIMIT 0, 10手动验证分页是否生效javaPageHelper.startPage(1, 10); ListUser list userMapper.selectList(); System.out.println(实际返回数量: list.size()); System.out.println(是否 Page 对象: (list instanceof Page)); // 如果 list.size() 一直等于全部数据说明分页未生效六、结合你的代码场景分析你之前的代码javapublic ListCarInspection search(MapString, Object params) { PageHelper.startPage(request.getPageNum(), request.getPageSize(), create_time DESC); ListCarInspection carInspections mapper.search(params); if (CollectionUtils.isNotEmpty(carInspections)) { // 补充机构名称、车辆别名等信息... return carInspections.stream().map(x - { x.setOrganizationName(orgInfo.get(...)); x.setVehicleAlias(plateNumCodes.get(...)); return x; }).collect(Collectors.toList()); // ← 这里丢失了 Page 类型 } return carInspections; }问题stream().collect(Collectors.toList())将Page对象转成了普通List导致分页信息丢失。✅ 修复javapublic PageInfoCarInspection search(MapString, Object params) { PageHelper.startPage(request.getPageNum(), request.getPageSize(), create_time DESC); ListCarInspection carInspections mapper.search(params); if (CollectionUtils.isNotEmpty(carInspections)) { // 直接用 for 循环修改不要 collect for (CarInspection x : carInspections) { x.setOrganizationName(orgInfo.get(...)); x.setVehicleAlias(plateNumCodes.get(...)); } } return new PageInfo(carInspections); // ✅ 返回 PageInfo }七、总结失效原因解决方案startPage后没有立即执行查询紧挨着调用 Mapper 方法中间有其他select操作拆分方法或确保只查一次循环中使用抽取为独立方法或用clearPage事务内使用将分页查询移出事务分页结果被转成普通List返回PageInfo或Page对象多数据源冲突确认DS与PageHelper在同一上下文中核心原则PageHelper.startPage()必须紧挨着需要分页的 Mapper 查询且查询结果需要保留Page类型或用PageInfo包装。
