深入理解分页及 PageHelper 使用细节与注意事项

深入理解分页及 PageHelper 使用细节与注意事项分页是现代应用开发中必不可少的一环，尤其在面对大数据量的场景时，通过分页可以有效减少单次查询的返回数据量，提升性能和用户体验。在 Java 开发中，PageHelper 是一个非常流行的分页插件，简单易用。然而，如果对其原理和使用细节不够了解，在实际使用中容易掉坑。本文将详细介绍 PageHelper 的工作机制、使用方法、常见问题及解决方案，帮助开发者正确使用它，避免踩坑。

一、PageHelper 的基本使用1. 配置 PageHelper在使用 PageHelper 之前，需要引入相关依赖：

代码语言：javascript复制

com.github.pagehelper

pagehelper-spring-boot-starter

1.4.6

如果使用的是 Spring Boot 项目，只需引入以上依赖即可，无需额外配置。PageHelper 会自动集成 MyBatis。

2. 使用方式PageHelper 的核心方法是 PageHelper.startPage()，它的作用是为当前线程开启分页上下文，并在接下来的查询中拦截 SQL，添加分页参数。

以下是典型的分页代码示例：

代码语言：javascript复制PageHelper.startPage(inputDto.getPageNum(), inputDto.getPageSize());

List configList = devicePushConfigMapper.queryDevicePushConfigList(query);

PageInfo pageInfo = new PageInfo<>(configList);执行流程：

PageHelper.startPage() 开启分页上下文，并设置分页参数。查询方法 devicePushConfigMapper.queryDevicePushConfigList(query) 被拦截，PageHelper 在 SQL 后自动添加 LIMIT。查询返回结果后，使用 PageInfo 封装结果，同时计算总记录数、分页信息等。二、PageHelper 的工作机制PageHelper 利用 MyBatis 的插件机制拦截查询语句，在查询 SQL 中自动加入分页语法，如 MySQL 的 LIMIT 或 Oracle 的 ROWNUM，并执行两次 SQL 查询：

查询总记录数：执行 SELECT COUNT(*) FROM ... 获取满足条件的记录总数。查询分页数据：在原始查询 SQL 后追加分页条件。三、PageHelper 使用中的常见问题及解决方法1. 分页上下文未清理导致干扰问题如果在同一线程中多次调用 PageHelper.startPage()，而未清理上下文，后续查询可能会受到前一次分页的影响。

场景代码语言：javascript复制PageHelper.startPage(1, 10);

List listA = mapperA.queryDataA(); // 第一次分页查询

PageHelper.startPage(2, 5);

List listB = mapperB.queryDataB(); // 第二次分页查询

PageInfo pageInfoA = new PageInfo<>(listA); // 结果可能被第二次分页干扰解决方法在每次分页查询后，调用 PageHelper.clearPage() 清理上下文。

代码语言：javascript复制PageHelper.startPage(1, 10);

List listA = mapperA.queryDataA();

PageInfo pageInfoA = new PageInfo<>(listA);

PageHelper.clearPage(); // 清理上下文

PageHelper.startPage(2, 5);

List listB = mapperB.queryDataB();

PageInfo pageInfoB = new PageInfo<>(listB);

PageHelper.clearPage();2. 查询未执行导致上下文污染问题如果分页查询代码在条件分支中，而分支未被执行，分页上下文未被清理会干扰后续查询。

场景代码语言：javascript复制PageHelper.startPage(1, 10);

if (someCondition) {

List list = mapper.queryData(); // 查询未执行

}

// 后续查询会被干扰解决方法将分页查询代码移到条件分支内部，确保分页逻辑与查询一一对应。在条件分支中调用 PageHelper.clearPage() 清理上下文。3. 数据转换后分页信息丢失问题如果分页查询返回的结果被转换为另一种类型（例如 DTO），再使用 PageInfo 封装，可能会导致分页总数信息丢失。

场景代码语言：javascript复制PageHelper.startPage(1, 10);

List configList = mapper.queryDevicePushConfigList(query);

// 数据转换

List result = new ArrayList<>();

for (DevicePushConfig config : configList) {

DevicePushConfigOutputDto dto = new DevicePushConfigOutputDto();

BeanUtils.copyProperties(config, dto);

result.add(dto);

}

// 使用 PageInfo 封装

PageInfo pageInfo = new PageInfo<>(result); // 总数信息丢失解决方法分页封装应基于原始查询结果，然后再进行数据转换：

代码语言：javascript复制PageHelper.startPage(1, 10);

List configList = mapper.queryDevicePushConfigList(query);

PageInfo pageInfo = new PageInfo<>(configList);

// 数据转换

List result = pageInfo.getList().stream()

.map(config -> {

DevicePushConfigOutputDto dto = new DevicePushConfigOutputDto();

BeanUtils.copyProperties(config, dto);

return dto;

})

.collect(Collectors.toList());

pageInfo.setList(result);4. 分页与排序冲突问题如果分页查询包含排序逻辑，而排序字段未建立索引，可能导致性能问题。

场景代码语言：javascript复制SELECT * FROM table_a

ORDER BY create_time

LIMIT 0, 10;解决方法确保排序字段上建立索引。对于大表分页，可以使用基于主键的范围查询优化：代码语言：javascript复制SELECT * FROM table_a

WHERE id > #{lastId}

ORDER BY id ASC

LIMIT 10;5. 重复分页问题分页逻辑已经通过数据库完成，如果开发者额外对结果进行代码级分页，可能导致结果不完整。

场景代码语言：javascript复制PageHelper.startPage(1, 10);

List dataList = mapper.queryData();

// 再次手动分页

List pagedResult = dataList.subList(0, Math.min(dataList.size(), 5));解决方法避免重复分页，直接使用 PageInfo 提供的分页信息：

代码语言：javascript复制PageHelper.startPage(1, 10);

List dataList = mapper.queryData();

PageInfo pageInfo = new PageInfo<>(dataList);四、总结PageHelper 是一个非常强大的分页工具，但其使用过程中需要注意以下细节：

分页上下文管理：分页查询后必须清理上下文，防止干扰后续查询。查询逻辑顺序：确保 PageHelper.startPage() 在查询前调用。数据转换问题：封装分页对象时，注意保持分页信息的一致性。性能优化：复杂 SQL 或排序字段需优化索引，避免全表扫描。避免重复分页：不要对已分页的数据再进行代码级分页。通过正确理解和使用 PageHelper，开发者可以高效完成分页需求，同时规避潜在问题，提升系统性能与稳定性。