当前位置：首页 > ops >正文

【MyBatis-9】MyBatis分页插件PageHelper深度解析与实践指南

ops 2025/8/26 13:01:31

1. 为什么需要分页插件？

在数据库操作中，分页查询是最常见的需求之一。传统的分页方式通常有两种：

内存分页：一次性查询所有数据，然后在内存中进行分页处理
SQL分页：通过SQL的LIMIT、ROWNUM等语法实现分页

第一种方式在数据量大时会导致内存溢出和性能问题，第二种方式虽然效率高但需要编写复杂且数据库特定的SQL语句。MyBatis作为优秀的ORM框架，本身并未提供统一的分页解决方案，这正是PageHelper诞生的背景。

2. PageHelper简介

PageHelper是国内开发者开发的一款MyBatis分页插件，具有以下特点：

支持多种数据库（MySQL、Oracle、PostgreSQL等）
使用简单，只需在查询前设置分页参数
物理分页，避免内存溢出
支持多种分页方式
开源免费，社区活跃

3. PageHelper集成与配置

3.1 添加依赖

Maven项目添加以下依赖：

<dependency><groupId>com.github.pagehelper</groupId><artifactId>pagehelper</artifactId><version>5.3.2</version> <!-- 使用最新版本 -->
</dependency>

3.2 MyBatis配置

在MyBatis配置文件中添加插件：

<plugins><plugin interceptor="com.github.pagehelper.PageInterceptor"><!-- 配置方言，默认会自动检测 --><property name="helperDialect" value="mysql"/><!-- 分页合理化，页码<=0时查询第一页，>=最大页时查询最后一页 --><property name="reasonable" value="true"/><!-- 支持通过Mapper接口参数来传递分页参数 --><property name="supportMethodsArguments" value="true"/><!-- 总是返回PageInfo类型,默认检查到Page参数不再处理 --><property name="returnPageInfo" value="check"/></plugin>
</plugins>

Spring Boot项目可以在application.properties中配置：

# PageHelper配置
pagehelper.helper-dialect=mysql
pagehelper.reasonable=true
pagehelper.support-methods-arguments=true
pagehelper.params=count=countSql

4. 基本使用方式

4.1 最简单的使用方式

// 设置分页参数，查询第1页，每页10条
PageHelper.startPage(1, 10);
// 紧跟着的第一个select方法会被分页
List<User> users = userMapper.selectAll();
// 用PageInfo对结果进行包装
PageInfo<User> pageInfo = new PageInfo<>(users);

4.2 PageInfo对象解析

PageInfo包含了丰富的分页信息：

// 当前页
pageInfo.getPageNum();
// 每页的数量
pageInfo.getPageSize();
// 当前页的数量
pageInfo.getSize();
// 总记录数
pageInfo.getTotal();
// 总页数
pageInfo.getPages();
// 结果集
pageInfo.getList();
// 是否为第一页
pageInfo.isIsFirstPage();
// 是否为最后一页
pageInfo.isIsLastPage();

4.3 更多使用方式

参数方式调用：

// 接口方法
List<User> selectByPage(@Param("name") String name, @Param("pageNum") int pageNum,@Param("pageSize") int pageSize);// 调用方式
userMapper.selectByPage("张三", 1, 10);

使用RowBounds参数：

RowBounds rowBounds = new RowBounds(0, 10);
List<User> users = userMapper.selectByRowBounds(null, rowBounds);

5. 高级特性与最佳实践

5.1 分页插件原理

PageHelper通过MyBatis的拦截器(Interceptor)机制实现，在SQL执行前动态修改SQL语句：

拦截Executor的query方法
获取分页参数
根据数据库方言重写SQL
执行COUNT查询获取总数
执行分页SQL获取结果集
封装分页结果

5.2 多表关联查询优化

对于复杂SQL，PageHelper的COUNT查询可能会很慢，可以自定义COUNT查询：

<select id="selectUserWithRole" resultMap="userWithRoleMap">select u.*, r.role_name from user u left join role r on u.role_id = r.id
</select><!-- 自定义count查询 -->
<select id="selectUserWithRole_COUNT" resultType="long">select count(1) from user u
</select>

5.3 分页性能优化

合理设置pageSize：避免单页数据量过大
只查询必要字段：避免SELECT *
使用索引：确保分页查询的WHERE条件有索引支持
缓存COUNT结果：对于变化不频繁的数据可以缓存总数

5.4 特殊数据库支持

对于不同数据库，PageHelper会自动使用不同的分页方式：

MySQL: LIMIT
Oracle: ROWNUM
PostgreSQL: LIMIT OFFSET
SQLServer: TOP

6. 常见问题与解决方案

6.1 分页不生效

可能原因：

PageHelper.startPage()后没有立即执行查询
方法被其他拦截器提前处理
配置不正确

解决方案：

// 确保调用模式正确
PageHelper.startPage(1, 10);
List<User> list = userMapper.selectAll();

6.2 排序问题

// 错误的排序方式
PageHelper.startPage(1, 10);
PageHelper.orderBy("id desc"); // 这行不会生效// 正确的排序方式
PageHelper.startPage(1, 10, "id desc");

6.3 多数据源配置

对于多数据源系统，需要为每个SqlSessionFactory单独配置PageHelper：

@Bean
@ConfigurationProperties(prefix = "pagehelper")
public Properties pageHelperProperties() {return new Properties();
}@Bean(name = "pageHelperInterceptor")
public PageInterceptor pageHelperInterceptor() {PageInterceptor pageInterceptor = new PageInterceptor();pageInterceptor.setProperties(pageHelperProperties());return pageInterceptor;
}// 为每个SqlSessionFactory添加插件
@Bean
public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {SqlSessionFactoryBean factory = new SqlSessionFactoryBean();factory.setDataSource(dataSource);// 添加其他配置...factory.setPlugins(new Interceptor[]{pageHelperInterceptor()});return factory.getObject();
}

7. PageHelper与MyBatis-Plus分页对比

特性	PageHelper	MyBatis-Plus分页
集成方式	插件形式	内置支持
使用复杂度	简单	简单
多数据库支持	支持	支持
分页原理	拦截器重写SQL	拦截器重写SQL
功能丰富度	专注于分页	与MP其他功能集成
社区活跃度	高	高