PageHelper分页失效？5个常见坑点及解决方案（附真实案例）

PageHelper分页失效5个常见坑点及解决方案附真实案例在MyBatis开发中PageHelper作为最流行的分页插件极大简化了分页查询的实现。然而在实际项目中开发者常常遇到分页失效的灵异事件——明明调用了startPage方法返回的却是全部数据。本文将深入分析5种典型场景通过真实案例还原问题本质并提供可直接落地的解决方案。1. 集合操作导致分页参数丢失典型场景对分页查询结果进行二次处理时无意中破坏了分页结构。例如// 错误示例 PageHelper.startPage(1, 10); ListProduct products productDAO.listProducts(); products.add(new Product()); // 添加元素 products.remove(0); // 删除元素 return new PageInfo(products);问题分析PageInfo构造函数要求传入的集合必须是原始分页查询结果任何对集合的增删操作都会导致分页元信息总条数、页码等计算错误返回的PageInfo对象中页码信息可能显示正确但实际数据条数与pageSize不符解决方案// 正确做法 PageHelper.startPage(1, 10); ListProduct originList productDAO.listProducts(); ListProduct processedList originList.stream() .map(this::processProduct) .collect(Collectors.toList()); PageInfoProduct pageInfo new PageInfo(originList); pageInfo.setList(processedList); return pageInfo;关键点保持原始查询集合不变通过setList方法注入处理后的数据2. 线程池引发的ThreadLocal污染并发场景下的经典问题GetMapping(/concurrent) public void concurrentTest() { threadPool.execute(() - { PageHelper.startPage(1, 10); // 分页参数存入ThreadLocal productDAO.listProducts(); // 正常分页查询 }); // 线程复用导致分页参数泄露 threadPool.execute(() - { productDAO.listProducts(); // 意外被分页 }); }问题本质PageHelper通过ThreadLocal存储分页参数线程池复用线程时未清理ThreadLocal后续查询意外继承分页参数防御方案方案类型实现方式适用场景同步清理PageHelper.clearPage()简单异步场景装饰线程ThreadLocalUtil.wrapRunnable()复杂线程池环境Lambda语法doSelectPage(() - {...})JDK8项目最佳实践// 使用Lambda避免内存泄漏 PageProduct page PageHelper.startPage(1, 10) .doSelectPage(() - productDAO.listProducts());3. 分页拦截器配置异常常见配置问题未正确注册拦截器多数据源场景配置冲突特殊SQL语法不支持Spring Boot配置要点# application.yml pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql多数据源注意事项明确指定autoRuntimeDialect: true不同数据源使用不同dialect别名避免重复注册拦截器排查工具在日志中搜索PageHelper关键词确认拦截器是否生效4. 特殊查询场景限制PageHelper对某些特殊查询存在兼容性问题不支持的情况包含FOR UPDATE的锁定查询嵌套结果映射Nested ResultMap存储过程调用使用UNION的复合查询替代方案/* 原生分页查询示例 */ SELECT * FROM ( SELECT id, name FROM product WHERE status 1 ORDER BY create_time DESC ) temp LIMIT 0, 105. 分页参数边界条件容易忽略的细节pageSize0时会返回全部数据reasonable参数对页码的自动修正参数传递类型不匹配参数处理最佳实践public PageInfoProduct queryProducts(PageParam param) { // 参数校验 if (param.getPageSize() 0) { param.setPageSize(10); // 默认值 } // 分页查询 PageHelper.startPage(param.getPageNum(), param.getPageSize()); ListProduct list productDAO.queryByCondition(param); return new PageInfo(list); }关键检查点确认传入参数是否为基本类型避免Integer判空问题检查是否配置了pageSizeZero参数验证reasonable参数是否符合业务预期在实际项目中遇到分页问题时建议按照以下流程排查检查SQL日志确认是否生成LIMIT子句验证ThreadLocal是否及时清理检查返回集合是否为原始查询结果确认拦截器配置是否正确加载排除特殊SQL语法限制