1. 项目概述在Spring Boot项目中整合MyBatis进行数据库操作时分页查询是最常见的需求之一。传统的分页实现方式往往需要在SQL中手动编写limit语句这种方式不仅繁琐而且难以维护。PageHelper作为MyBatis的物理分页插件通过拦截器机制自动处理分页逻辑让开发者只需关注业务查询本身。我在多个企业级项目中实际使用PageHelper后发现它能够将原本需要10-20行代码的分页逻辑简化为2-3行配置同时支持多种数据库方言包括MySQL、Oracle、PostgreSQL等主流数据库。最新版本的PageHelper 6.x已全面支持JDK8特性与Spring Boot 3.x也能完美兼容。2. 核心原理与配置2.1 分页插件工作原理PageHelper基于MyBatis的Interceptor机制实现。当执行Mapper方法时插件会拦截Executor的query方法通过解析ThreadLocal中存储的分页参数自动重写原始SQL语句。以MySQL为例原始SQLSELECT * FROM user WHERE status 1添加分页后会被改写为SELECT * FROM user WHERE status 1 LIMIT 0,10这种物理分页方式相比内存分页先查询全部数据再截取性能更高特别是在大数据量场景下差异明显。2.2 Spring Boot集成配置在pom.xml中添加依赖建议使用最新稳定版dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version /dependencyapplication.yml基础配置示例pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql关键参数说明helper-dialect指定数据库方言reasonable分页合理化超出总页数时返回最后一页params分页参数别名设置3. 实际应用详解3.1 基础分页查询在Service层实现典型分页查询public PageInfoUser getUsers(int pageNum, int pageSize) { PageHelper.startPage(pageNum, pageSize); ListUser users userMapper.selectAll(); return new PageInfo(users); }PageHelper.startPage()方法会设置线程本地分页参数接下来的第一个查询语句会自动应用分页。PageInfo对象包含丰富的分页信息当前页码pageNum每页数量pageSize总记录数total总页数pages实际数据列表list3.2 复杂多表分页对于多表关联查询PageHelper同样适用public PageInfoUserDTO getUsersWithRoles(int pageNum) { PageHelper.startPage(pageNum, 10); ListUserDTO list userMapper.selectUsersWithRoles(); return new PageInfo(list); }对应的Mapper XMLselect idselectUsersWithRoles resultTypeUserDTO SELECT u.*, r.role_name FROM user u LEFT JOIN user_role ur ON u.id ur.user_id LEFT JOIN role r ON ur.role_id r.id /select3.3 分页排序功能结合排序参数使用public PageInfoUser getUsersSorted(int pageNum, String orderBy) { PageHelper.startPage(pageNum, 10).setOrderBy(orderBy); return new PageInfo(userMapper.selectAll()); }调用示例// 按创建时间倒序 pageInfo userService.getUsersSorted(1, create_time desc);4. 高级特性与优化4.1 自定义分页SQL对于特殊分页需求可以使用SelectProvider注解SelectProvider(type UserSqlBuilder.class, method buildSelectByExample) ListUser selectByExample(UserExample example); class UserSqlBuilder { public String buildSelectByExample(UserExample example) { return new SQL() {{ SELECT(*); FROM(user); if (example.getStatus() ! null) { WHERE(status #{status}); } }}.toString(); } }4.2 分页性能优化COUNT查询优化pagehelper: count-suffix: _COUNT对应Mapper中定义专用count查询select idselectAll_COUNT resultTypelong SELECT COUNT(1) FROM user /select禁用不必要的count查询PageHelper.startPage(1, 10, false); // 第三个参数设为false跳过count4.3 多数据源支持在多数据源环境下需要为每个数据源单独配置方言Bean ConfigurationProperties(prefix spring.datasource.ds1) public DataSource ds1() { return DataSourceBuilder.create().build(); } Bean public PageInterceptor pageInterceptor() { PageInterceptor interceptor new PageInterceptor(); Properties props new Properties(); props.setProperty(helperDialect, mysql); interceptor.setProperties(props); return interceptor; }5. 常见问题排查5.1 分页失效场景未遵循调用规范// 错误示例startPage与查询语句不在同一线程 new Thread(() - { userMapper.selectAll(); }).start(); // 正确做法 PageHelper.startPage(1, 10); userMapper.selectAll();分页语句后存在其他查询PageHelper.startPage(1, 10); userMapper.selectAll(); // 这个会被分页 userMapper.selectOther(); // 这个也会被分页解决方案使用PageHelper.clearPage()清除分页参数5.2 特殊数据库适配对于达梦等特殊数据库需配置dialectAliaspagehelper: dialect-alias: dmoracle5.3 与MyBatis-Plus共存同时使用PageHelper和MyBatis-Plus时需注意拦截器顺序Bean Order(0) // 确保先执行 public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); return interceptor; } Bean Order(1) public PageInterceptor pageInterceptor() { return new PageInterceptor(); }6. 最佳实践建议统一分页参数处理public class PageRequest { Min(1) private int pageNum 1; Range(min 1, max 100) private int pageSize 10; private String orderBy; }全局响应封装public class PageResultT { private long total; private ListT rows; public static T PageResultT of(PageInfoT pageInfo) { PageResultT result new PageResult(); result.setTotal(pageInfo.getTotal()); result.setRows(pageInfo.getList()); return result; } }前端分页组件对接// VueElementUI示例 el-pagination :current-pagequeryParams.pageNum :page-sizequeryParams.pageSize :totaltotal current-changehandlePageChange /在实际项目开发中我发现合理设置pageSize默认值非常重要。根据业务场景通常建议后台管理系统10-20条/页移动端列表5-10条/页报表导出可设置较大值如1000条对于超大数据量的分页如百万级建议采用上一页/下一页模式而非直接跳页可以通过记录上一页最后一条记录的ID来实现高效分页SELECT * FROM table WHERE id #{lastId} ORDER BY id LIMIT 10