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

简介

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

安装

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

    com.github.pagehelper
    pagehelper
    最新版本

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

示例

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

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

  
  
    
      
        
          
          
            params=value1
          
        
      
    
  

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 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 list = userMapper.selectIf(1);
assertEquals(2, list.get(0).getId());
assertEquals(10, list.size());
//分页时，实际返回的结果list类型是Page，如果想取出分页信息，需要强制转换为Page
assertEquals(182, ((Page) list).getTotal());

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

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

//后面的不会被分页，除非再次调用PageHelper.startPage
List 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 配置：

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

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

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

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

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

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

• ISelect 接口方式

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

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

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

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

总结

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