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

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

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

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

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

2. PageHelper简介

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

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

3. PageHelper集成与配置

3.1 添加依赖

Maven项目添加以下依赖：

xml 复制代码

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

3.2 MyBatis配置

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

xml 复制代码

<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中配置：

properties 复制代码

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

4. 基本使用方式

4.1 最简单的使用方式

java 复制代码

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

4.2 PageInfo对象解析

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

java 复制代码

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

4.3 更多使用方式

参数方式调用：

java 复制代码

// 接口方法
List<User> selectByPage(@Param("name") String name, 
                       @Param("pageNum") int pageNum,
                       @Param("pageSize") int pageSize);

// 调用方式
userMapper.selectByPage("张三", 1, 10);

使用RowBounds参数：

java 复制代码

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查询：

xml 复制代码

<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()后没有立即执行查询
方法被其他拦截器提前处理
配置不正确

解决方案：

java 复制代码

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

6.2 排序问题

java 复制代码

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

// 正确的排序方式
PageHelper.startPage(1, 10, "id desc");

6.3 多数据源配置

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

java 复制代码

@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其他功能集成
社区活跃度	高	高

选择建议：

如果项目已经使用MyBatis-Plus，可以直接使用其分页功能
如果使用原生MyBatis，PageHelper是更好的选择

8. 总结

PageHelper作为MyBatis生态中最流行的分页插件，具有简单易用、功能强大、性能优异等特点。通过本文的介绍，你应该已经掌握了：

PageHelper的基本原理与配置方式
多种分页使用方法
性能优化技巧
常见问题解决方案

在实际项目中，合理使用PageHelper可以大幅提升开发效率，同时保证分页查询的性能。建议根据项目需求选择合适的配置方式，并遵循最佳实践来获得最佳体验。