PageHelper

PageHelper是 MyBatis 框架下应用最广泛的分页插件能让你免去手写LIMIT等分页语句的繁琐工作。它通过拦截 SQL 并自动为其添加分页语法如 MySQL 的LIMIT来工作。 为什么需要 PageHelper当数据量大时一次性查询所有数据会导致性能问题。PageHelper的价值在于简化开发无需手动拼接分页 SQL只需调用startPage方法即可。减少错误自动处理不同数据库的分页方言避免了手写 SQL 可能出现的错误。功能全面能自动查询总记录数并提供了PageInfo类来封装总页数、导航页码等丰富信息。⚙️ 工作原理PageHelper的核心机制如下存储参数调用PageHelper.startPage(pageNum, pageSize)时分页参数被存入当前线程的ThreadLocal变量中。拦截 SQLMyBatis 执行查询时PageHelper的拦截器会拦截该 SQL。改写 SQL拦截器从ThreadLocal取出分页参数并根据数据库方言在原始 SQL 后动态添加分页语句如LIMIT。执行 COUNT自动执行SELECT COUNT(*)获取总记录数。清理上下文分页完成后自动清除ThreadLocal中的参数避免线程池复用带来干扰。 快速上手1. 添加依赖对于 Spring Boot 项目推荐使用pagehelper-spring-boot-starter。xmldependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.7/version !-- 建议使用最新稳定版 -- /dependency2. 配置可选在 Spring Boot 的application.yml文件中进行配置。yamlpagehelper: helper-dialect: mysql # 指定数据库方言可自动识别[reference:21] reasonable: true # 分页合理化如页码超出范围时自动修正[reference:22] support-methods-arguments: true # 支持通过 Mapper 方法参数传递分页参数[reference:23]3. 核心代码标准的编码模式是设置分页 - 执行查询 - 封装结果。java// 1. 设置分页参数 PageHelper.startPage(pageNum, pageSize); // 2. 执行查询此查询会被自动分页 ListUser userList userMapper.selectAllUsers(); // 3. 使用 PageInfo 封装结果获取分页信息 PageInfoUser pageInfo new PageInfo(userList);其中PageInfo对象包含了total(总记录数)、pages(总页数)、pageNum(当前页码) 等非常详细的属性。⚠️ 常见问题与避坑指南startPage无效确保PageHelper.startPage()调用后紧跟的是第一个MyBatis 查询方法。两者之间不要有其他无关的查询或代码。分页上下文未清理在同一个线程中连续分页可能相互干扰。建议在每次分页操作后调用PageHelper.clearPage()手动清理。PageHelper与MyBatis-Plus冲突MyBatis-Plus自带分页插件两者同时使用会冲突。如果项目使用了MyBatis-Plus应使用其内置的分页功能并移除PageHelper依赖。COUNT 查询性能问题对于复杂 SQL自动生成的COUNT查询可能很慢。可通过配置countcountSql参数进行优化。版本与配置问题若从 4.x 升级到 5.x拦截器类名已变需确保配置正确。非 Spring Boot 项目需在 MyBatis 配置文件 (mybatis-config.xml) 中正确配置PageInterceptor。特殊 SQL 问题PageHelper不支持包含FOR UPDATE的 SQL对于此类 SQL 建议自行手动处理分页。 总结PageHelper是简化 MyBatis 分页操作的利器。它的核心用法就是三步startPage- 执行查询 -PageInfo封装。使用时关键是要注意startPage必须紧跟查询并留意线程上下文和版本配置的细节。对于更特殊或复杂的场景可以查阅其 官方文档 以获得更深入的信息。