SpringBoot项目实战：手把手教你用MyBatis+PageHelper搞定员工分页查询（附完整XML配置）
SpringBoot实战：MyBatis+PageHelper实现高效分页查询
在企业级应用开发中，数据分页查询是最基础也最频繁使用的功能之一。传统的手动分页方式不仅代码冗余，而且难以应对复杂查询场景。本文将深入讲解如何利用MyBatis结合PageHelper插件，构建一个既简洁又强大的分页查询解决方案。
1. 分页技术选型与对比
在Java Web开发中，分页实现主要有三种方式：原生SQL分页、手动计算分页和使用分页插件。让我们通过一个员工管理系统的案例，分析不同方案的优劣。
原生SQL分页通过在SQL语句中添加LIMIT子句实现：
SELECT * FROM emp LIMIT 0, 10这种方式简单直接，但存在明显缺陷：
- 需要手动计算偏移量
- 无法获取总记录数
- 不同数据库语法差异大（MySQL用LIMIT，Oracle用ROWNUM）
手动分页是更完整的解决方案，通常需要两条SQL：
// 查询总数 SELECT COUNT(*) FROM emp WHERE [条件] // 查询当前页数据 SELECT * FROM emp WHERE [条件] LIMIT ?,?虽然功能完整，但存在以下问题：
- 代码重复率高
- 分页逻辑与业务逻辑耦合
- 多表联查时复杂度指数级上升
相比之下，PageHelper插件提供了声明式的分页方案：
PageHelper.startPage(1, 10); // 第1页，每页10条 List<Emp> emps = empMapper.selectByCondition(params);优势包括：
- 自动处理分页参数
- 支持多种数据库
- 与MyBatis无缝集成
- 提供丰富的分页信息（总页数、当前页等）
提示：PageHelper底层通过MyBatis拦截器实现，对业务代码零侵入，是SpringBoot项目中分页的首选方案。
2. 环境配置与基础集成
2.1 依赖引入与基础配置
在SpringBoot项目中集成PageHelper需要以下步骤：
- 添加Maven依赖：
<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper-spring-boot-starter</artifactId> <version>1.4.6</version> </dependency>- 配置application.yml：
pagehelper: helper-dialect: mysql # 数据库方言 reasonable: true # 分页参数合理化 support-methods-arguments: true # 支持接口参数关键配置参数说明：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| helper-dialect | String | - | 数据库方言(mysql,oracle等) |
| reasonable | Boolean | false | 合理化分页参数(超出范围自动调整) |
| support-methods-arguments | Boolean | false | 支持Mapper接口参数传递 |
| params | String | pageNum=pageNumKey... | 分页参数别名映射 |
2.2 基本使用模式
PageHelper提供了两种启动分页的方式：
方式一：静态方法调用
public PageInfo<Emp> queryEmpList(int pageNum, int pageSize, EmpQuery params) { PageHelper.startPage(pageNum, pageSize); List<Emp> list = empMapper.selectByCondition(params); return new PageInfo<>(list); }方式二：接口参数传递
public PageInfo<Emp> queryEmpList(EmpQuery params) { // 参数名需与配置的params对应 List<Emp> list = empMapper.selectByCondition(params); return new PageInfo<>(list); }注意：PageHelper.startPage()必须紧邻Mapper查询语句，中间不能有其它数据库操作，否则会导致分页失效。
3. 复杂查询场景实战
实际项目中，分页往往需要配合条件查询、排序等复杂场景。下面通过员工管理系统案例，演示如何实现多功能分页查询。
3.1 多条件动态查询
MyBatis的动态SQL与PageHelper完美配合，可以构建灵活的分页查询：
Mapper接口定义：
public interface EmpMapper { List<Emp> selectByCondition(@Param("name") String name, @Param("gender") Integer gender, @Param("deptId") Integer deptId, @Param("startDate") Date startDate, @Param("endDate") Date endDate); }XML映射文件：
<select id="selectByCondition" resultType="com.example.pojo.Emp"> SELECT * FROM emp <where> <if test="name != null and name != ''"> AND name LIKE CONCAT('%',#{name},'%') </if> <if test="gender != null"> AND gender = #{gender} </if> <if test="deptId != null"> AND dept_id = #{deptId} </if> <if test="startDate != null and endDate != null"> AND entry_date BETWEEN #{startDate} AND #{endDate} </if> </where> ORDER BY update_time DESC </select>Service层实现：
public PageInfo<Emp> queryEmpPage(EmpQuery query) { PageHelper.startPage(query.getPageNum(), query.getPageSize()); List<Emp> list = empMapper.selectByCondition( query.getName(), query.getGender(), query.getDeptId(), query.getStartDate(), query.getEndDate() ); return new PageInfo<>(list); }3.2 排序与多字段排序
PageHelper支持通过PageHelper.orderBy()方法添加排序：
public PageInfo<Emp> queryEmpPage(EmpQuery query) { // 单字段排序 PageHelper.startPage(query.getPageNum(), query.getPageSize()) .orderBy("update_time desc"); // 多字段排序 String orderBy = StringUtils.isBlank(query.getOrderBy()) ? "update_time desc" : query.getOrderBy(); PageHelper.startPage(query.getPageNum(), query.getPageSize()) .orderBy(orderBy); List<Emp> list = empMapper.selectByCondition(...); return new PageInfo<>(list); }3.3 分页结果封装
PageHelper提供了PageInfo类封装分页结果，包含丰富的信息：
public class PageResult<T> { private int pageNum; // 当前页 private int pageSize; // 每页数量 private long total; // 总记录数 private int pages; // 总页数 private List<T> list; // 数据列表 // 其他预计算属性... } // 使用示例 PageInfo<Emp> pageInfo = new PageInfo<>(empList); return new PageResult<>( pageInfo.getPageNum(), pageInfo.getPageSize(), pageInfo.getTotal(), pageInfo.getPages(), pageInfo.getList() );4. 高级特性与性能优化
4.1 分页插件原理剖析
PageHelper通过MyBatis的Interceptor接口实现分页功能，核心流程如下：
- 拦截Executor.query()方法
- 解析分页参数，重写原始SQL
- 执行COUNT查询获取总数
- 添加LIMIT子句执行分页查询
- 封装分页结果
性能优化建议：
- 对于超大数据表，考虑使用延迟关联优化：
SELECT * FROM emp e JOIN (SELECT id FROM emp WHERE [条件] LIMIT ?,?) tmp ON e.id = tmp.id- 复杂查询可缓存COUNT结果
- 合理设置pageSize，避免单页数据过大
4.2 特殊场景处理
物理分页 vs 逻辑分页
PageHelper默认使用物理分页（数据库层面分页），对于小数据量也可配置逻辑分页：
pagehelper: offset-as-page-num: false # 默认false row-bounds-with-count: true # 逻辑分页时是否执行count查询一对多分页解决方案
当主表关联多个子表时，直接分页会导致结果不准确。解决方案：
- 先分页查询主表ID
- 根据主表ID查询完整数据
PageHelper.startPage(1, 10); List<Long> masterIds = masterMapper.selectIdsByCondition(params); List<Master> masters = masterMapper.selectWithDetailsByIds(masterIds);4.3 常见问题排查
问题1：分页失效可能原因：
- PageHelper.startPage()与Mapper调用之间有其他数据库操作
- 同一线程多次调用startPage()未清除
- 配置参数不正确
解决方案：
try { PageHelper.startPage(1, 10); // 业务代码 } finally { PageHelper.clearPage(); // 确保清除 }问题2：排序无效检查点：
- orderBy参数格式是否正确（"字段名 排序方式"）
- SQL中是否有ORDER BY冲突
- 是否使用了$而非#导致SQL注入
问题3：性能低下优化方向：
- 检查COUNT查询是否走索引
- 复杂查询考虑使用异步COUNT
- 大数据量考虑游标分页
5. 最佳实践与项目集成
5.1 统一分页响应封装
建议项目中统一分页响应格式，例如：
public class PageResponse<T> { private boolean success; private String message; private PageData<T> data; public static <T> PageResponse<T> success(PageInfo<T> pageInfo) { PageResponse<T> response = new PageResponse<>(); response.setSuccess(true); response.setData(new PageData<>( pageInfo.getPageNum(), pageInfo.getPageSize(), pageInfo.getTotal(), pageInfo.getList() )); return response; } }5.2 前端分页组件对接
与前端分页组件（如Element UI Pagination）对接时，注意参数映射：
// 请求参数 { pageNum: 1, pageSize: 10, orderBy: 'name asc,create_time desc' } // 响应数据 { "success": true, "data": { "list": [...], "total": 100, "pageNum": 1, "pageSize": 10, "pages": 10 } }5.3 微服务环境下的分页
在微服务架构中，分页查询需要注意：
- Feign客户端需特殊处理Pageable参数
- 跨服务分页考虑使用游标分页
- 分布式环境下COUNT查询可能成为瓶颈
// Feign接口示例 @GetMapping("/emps") PageResponse<Emp> queryEmpPage(@SpringQueryMap EmpQuery query);在实际项目中，分页功能看似简单，但要做到高性能、易维护需要综合考虑多种因素。通过合理使用PageHelper插件，配合MyBatis的动态SQL能力，可以大幅提升开发效率，同时保证系统的稳定性和扩展性。