分页，是实现数据库查询相关逻辑时不可避免的一部分。大量的数据，不可能也没必要一次性全部列出返回，往往需要通过分页的方式，进行逐页的查询。但如果每次查询都要手动去实现分页的逻辑，那也太麻烦了。而且，不同的数据库间的差异，也往往会使得分页查询的实现有所不同，一些特殊的边界情况考虑起来也比较复杂。PageHelper，这个号称最方便的 MyBatis 的开源分页插件，值得一试。

简介

PageHelper 是 pagehelper 在 Github 上开源的 MyBatis 分页插件，项目位于 https://github.com/pagehelper/Mybatis-PageHelper，目前版本为 5.2.0。PageHelper 支持任何复杂的单表、多表分页，支持几乎所有主流数据库的物理分页，包括 Oracle、MySQL、PostgreSQL 等，支持自动检测数据库选择合适的分页方式，支持页码方式和偏移量方式的分页，支持对参数自动合理化处理，支持多数据源自动识别分页方式等。

安装

PageHelper 可以通过 Maven 引入项目，在 pom.xml 中添加依赖：

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper</artifactId>
    <version>最新版本</version>
</dependency>

也可以手动引入 jar 包，在项目的 Release 页面下载最新的 jar 包，同时还需要下载 jsqlparser.jar 用于 SQL 解析。

示例

PageHelper 的使用，主要通过配置拦截器插件。可以在 MyBatis 配置 XML 中配置拦截器插件：

<plugins>
    <!-- com.github.pagehelper为PageHelper类所在包名 -->
    <plugin interceptor="com.github.pagehelper.PageInterceptor">
        <!-- 使用下面的方式配置参数，后面会有所有的参数介绍 -->
        <property name="param1" value="value1"/>
	</plugin>
</plugins>

也可以在 Spring 的配置文件中，使用属性配置方式配置插件：

<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
  <!-- 注意其他配置 -->
  <property name="plugins">
    <array>
      <bean class="com.github.pagehelper.PageInterceptor">
        <property name="properties">
          <!--使用下面的方式配置参数，一行配置一个 -->
          <value>
            params=value1
          </value>
        </property>
      </bean>
    </array>
  </property>
</bean>

PageHelper 提供了多个可选参数，可以根据自身项目的使用方式进行配置，参数包括：

• dialect：分页方式，提供了默认的 PageHelp 方式分页。如果想要实现自定义的分页逻辑，可以通过实现 com.github.pagehelper.Dialect 接口，然后配置 dialog 参数为实现类的全限定名称。
• helperDialet：指定分页插件的 SQL 方言。默认会进行自动检测，也可以手动指定，，可用的值包括：oracle,mysql,mariadb,sqlite,hsqldb,postgresql,db2,sqlserver,informix,h2,sqlserver2012,derby
• offsetAsPageNum：是否把 RowBounds 参数中的 offset 当作 pageNum 使用，实现页码和页面大小的分页方式，默认为 false。
• rowBoundsWithCount：是否在 RowBounds 分页时进行数据统计查询，默认为 false。
• pageSizeZero：是否支持当 pageSize = 0 或 RowBounds.limit = 0 时，进行全部结果查询，默认为 false。
• reasonable：是否对分页参数进行合理化处理，当 pageNum <= 0 时自动查询第一页，超过总数时查询最后一页，默认为 false。
• params：配置参数映射，用于从对象中根据属性名取值，可以配置 pageNum,pageSize, count, pageSizeZero, reasonable 参数。
• supportMethodsArguments：是否支持通过 Mapper 接口参数传递分页参数，默认为 false。
• autoRuntimeDialect：是否在运行时根据多数据源自动识别对应 SQL 方言的分页实现，默认为 false。
• closeConn：是否关闭动态获取数据库类型的连接，默认为 true。
• aggregateFunctions：常见数据库的聚合函数集合，允许手动添加聚合函数。

当完成了拦截器的配置后，可以在代码中进行分页插件的调用，支持多种调用方式，包括：

• RowBounds 方式

通过提供 RowBounds 参数进行分页，这种方法侵入性最小，并会自动进行物理分页：

List<User> list = sqlSession.selectList("x.y.selectIf", null, new RowBounds(0, 10));

默认情况下的 RowBounds 无法获取查询总数，如果需要进行 count 查询，PageHelper 提供了继承自 RowBounds 的 PageRowBounds，增加了 total 属性，可以获取查询总数。

• Mapper 接口方式 在需要进行分页的 MyBatis 查询方法前调用 PageHelper.startPage 或 PageHelper.offsetPage 静态方法，并传递参数，紧跟其后的其第一个 MyBatis 查询方法就会进行分页：

//获取第1页，10条内容，默认查询总数count
PageHelper.startPage(1, 10);
//紧跟着的第一个select方法会被分页
List<User> list = userMapper.selectIf(1);
assertEquals(2, list.get(0).getId());
assertEquals(10, list.size());
//分页时，实际返回的结果list类型是Page<E>，如果想取出分页信息，需要强制转换为Page<E>
assertEquals(182, ((Page) list).getTotal());

也可以传入 ServletRequest, Map, POJO 对象，实现自动参数解析

//request: url?pageNum=1&pageSize=10
//支持 ServletRequest,Map,POJO 对象，需要配合 params 参数
PageHelper.startPage(request);
//紧跟着的第一个select方法会被分页
List<User> list = userMapper.selectIf(1);

//后面的不会被分页，除非再次调用PageHelper.startPage
List<User> list2 = userMapper.selectIf(null);

//list1
assertEquals(2, list.get(0).getId());
assertEquals(10, list.size());

//list2
assertEquals(1, list2.get(0).getId());
assertEquals(182, list2.size());

• 参数方式 如果需要使用参数方式，需要配置 supportMethodsArguments 配置参数为 true，并提供 params 配置：

<plugins>
    <!-- com.github.pagehelper为PageHelper类所在包名 -->
    <plugin interceptor="com.github.pagehelper.PageInterceptor">
        <!-- 使用下面的方式配置参数，后面会有所有的参数介绍 -->
        <property name="supportMethodsArguments" value="true"/>
        <property name="params" value="pageNum=pageNumKey;pageSize=pageSizeKey;"/>
	</plugin>
</plugins>

在 MyBatis 方法中，就可以通过参数方式调用：

List<User> selectByPageNumSize(
        @Param("user") User user,
        @Param("pageNumKey") int pageNum, 
        @Param("pageSizeKey") int pageSize);

由于提供了已经配置的参数 pageNumKey 和 pageSizeKey，PageHelper 就会自动进行对应参数的分页：

List<User> list = userMapper.selectByPageNumSize(user, 1, 10);

如果对应的参数在对象中出现，那么也可以使用参数对象的方式进行调用：

public class User {
    //其他fields
    //下面两个参数名和 params 配置的名字一致
    private Integer pageNumKey;
    private Integer pageSizeKey;
}
//存在以下 Mapper 接口方法，你不需要在 xml 处理后两个参数
public interface CountryMapper {
    List<User> selectByPageNumSize(User user);
}
//当 user 中的对应的分页参数非空时，会自动分页
List<User> list = userMapper.selectByPageNumSize(user);

• ISelect 接口方式

可以使用 JDK 6 和 7 的方式，创建 ISelect 接口：

Page<User> page = PageHelper.startPage(1, 10).doSelectPage(new ISelect() {
    @Override
    public void doSelect() {
        userMapper.selectGroupBy();
    }
});

也可以简单使用 JDK 8 的 lambda：

Page<User> page = PageHelper.startPage(1, 10).doSelectPage(()-> userMapper.selectGroupBy());

总结

PageHelper 作为一个 MyBatis 分页插件，提供了丰富的配置参数和调用方式，支持的数据库广泛，使用简单方便，让开发者无需自行编写分页逻辑，隐去了各种底层细节，可以适应多种应用场景。PageHelper 项目代码规范，注释合理，文档详尽，并提供了 API 参考文档，和 Spring 与 Spring Boot 的集成示例，值得在项目中进行集成使用，并参考学习。