分页PageHelper

一、技术文档

1、基于SpringBoot

  • SpringBoot 官方文档：https://spring.io/projects/spring-boot

  • SpringBoot 中文社区：https://springboot.io/

    2、基于MyBatis

  • MyBatis 官方文档：https://mybatis.org/mybatis-3/zh/index.html

    3、集成PageHelper

  • PageHelper 开源仓库：https://github.com/pagehelper/Mybatis-PageHelper

    二、开发依赖

    SpringBoot

    1. <dependency>
    2. <groupId>org.springframework.boot</groupId>
    3. <artifactId>spring-boot-starter-web</artifactId>
    4. </dependency>

    MyBatis

    1. <dependency>
    2. <groupId>org.mybatis.spring.boot</groupId>
    3. <artifactId>mybatis-spring-boot-starter</artifactId>
    4. <version>2.1.3</version>
    5. </dependency>

    PageHelper

    1. <dependency>
    2. <groupId>com.github.pagehelper</groupId>
    3. <artifactId>pagehelper-spring-boot-starter</artifactId>
    4. <version>1.3.0</version>
    5. </dependency>

    三、应用讲解

    1、基本使用

    在实际项目运用中，PageHelper的使用非常便利快捷，仅通过PageInfo + PageHelper两个类，就足以完成分页功能，然而往往这种最简单的集成使用方式，却在很多实际应用场景中，没有得到充分的开发利用。
    下面是最常见的使用方式：

    1. public PageInfo<ResponseEntityDto> page(RequestParamDto param) {
    2.   PageHelper.startPage(param.getPageNum(), param.getPageSize());
    3.   List<ResoinseEntityDto> list = mapper.selectManySelective(param);
    4.   PageInfo<ResponseEntityDto> pageInfo = (PageInfo<ResponseEntityDto>)list;
    5.   return pageInfo;
    6. }

    在某种程度上而言，上述写法的确是符合PageHelper的使用规范：

    在集合查询前使用PageHelper.startPage(pageNum,pageSize)，并且中间不能穿插执行其他SQL

但是作为Developer，往往只有在追求完美和极致的道路上才能够寻得突破和机遇; 以下是合理且规范的基本使用：

  1. public PageInfo<ResponseEntityDto> page(RequestParamDto param) {
  2.     return PageHelper.startPage(param.getPageNum(), param.getPageSize())
  3.         .doSelectPageInfo(() -> list(param))
  4.     } 
  5. public List<ResponseEntityDto> list(RequestParamDto param) {
  6.     return mapper.selectManySelective(param);
  7. }

FAQ

1、为什么要重新声明一个list函数?

答：往往在很多实际业务应用场景中，分页查询是基于大数据量的表格展示需求来进行的。然而很多时候，譬如：内部服务的互相调用，OpenAPI的提供。甚至在某些前后端分离联调的业务场景中，是同样需要一个非分页集合查询接口来提供服务的。另外，暂时以上因素抛开不谈，可以根据上述写法来定义和规范某些东西譬如：分页和集合查询的分离和解耦(解耦详情请看进阶使用)，分页请求的请求和响应与实际业务参数的分离(详情请看进阶使用)等等…

2、doSelectPageInfo是什么?

答：doSelectPageInfo是PageHelper.startPage()函数返回的默认Page实例内置的函数，该函数可以用以Lambda的形式通过额外的Function来进行查询而不需要再进行多余的PageInfo与List转换，而doSelectPageInfo的参数则是PageHelper内置的Function(ISelect)接口用以达到转换PageInfo的目的

3、这种写法的代码量看起来不少反多?

答：正如同①中所描述的，就代码量而言，确实没有更进一步的简化，但是再某些业务场景中，在已具有list函数接口的情况下，是一种更直观的优化(优化详情请看进阶使用)

2、进阶使用

先看代码，再谈解析：

  1. import com.github.pagehelper.PageHelper;
  2. import com.github.pagehelper.PageInfo;
  3. import java.util.List;
  4. /**
  5.  * @param <Param> 泛型request
  6.  * @param <Result> 泛型response
  7.  */
  8. public interface BaseService<Param, Result> {
  9.     /**
  10.      * 分页查询
  11.      *
  12.      * @param param 请求参数DTO
  13.      * @return 分页集合
  14.      */
  15.     default PageInfo<Result> page(PageParam<Param> param) {
  16.         return PageHelper.startPage(param).doSelectPageInfo(() -> list(param.getParam()));
  17.     }
  18.     /**
  19.      * 集合查询
  20.      *
  21.      * @param param 查询参数
  22.      * @return 查询响应
  23.      */
  24.     List<Result> list(Param param);
  25. }

可以看到BaseService可以作为全局Service通用接口的封装和声明 而作为通用分页接口page函数却在此处利用interface特有关键字default 直接声明了page函数的方法体body

  1. import com.github.pagehelper.IPage;
  2. import lombok.Data;
  3. import lombok.experimental.Accessors;
  4. @Data // 为省略冗余代码使用lombok 实际应有常规Getter/Setter Construction toString等
  5. @Accessors(chain = true) // 此lombok注解是为了实现 Entity伪Build 譬如: entity.setX(x).setY(y)
  6. public class PageParam<T>  implements IPage {
  7.     //  description = "页码", defaultValue =  1
  8.     private Integer pageNum = 1;
  9.     // description = "页数", defaultValue = 20
  10.     private Integer pageSize = 20;
  11.     // description = "排序", example = "id desc"
  12.     private String orderBy;
  13.     //  description = "参数"
  14.     private T param;
  15.     public PageParam<T> setOrderBy(String orderBy) {
  16.         this.orderBy = orderBy; // 此处可优化 优化详情且看解析
  17.         return this;
  18.     }
  19. }

在BaseService中看到了一个新的PageParam，参考了PageInfo用以包装/声明/分离分页参数和业务参数，且参数类型为泛型，即支持任何数据类型的业务参数 同时也可以看到PageParam实现了IPage接口，并且多了一个orderBy属性字段

  1. import common.base.BaseService;
  2. import dto.req.TemplateReqDto;
  3. import dto.resp.TemplateRespDto;
  4. public interface TemplateService extends BaseService<TemplateReqDto, TemplateeRespDto> {
  5.     // 同为interface接口, 业务Service只需要继承BaseService
  6.     // 并根据实际使用场景声明请求参数和响应结果的Entity实体即可
  7. }

在实际应用中，只需要声明通用的业务查询请求参数和响应结果即可

  1. import dto.req.TemplateReqDto;
  2. import dto.resp.TemplateRespDto;
  3. import service.TemplateService;
  4. import persistence.mapper.TemplateMapper;
  5. import lombok.RequiredArgsConstructor;
  6. import lombok.extern.slf4j.Slf4j;
  7. import org.springframework.stereotype.Service;
  8. import java.util.List;
  9. @Slf4j // 基于lombok自动生成logger日志记录实例
  10. @Service // SpringBoot中注册Service Bean的注解
  11. @RequiredArgsConstructor // 基于lombok根据类所有final属性生成构造函数 即可完成Spring构造注入
  12. public class TemplateServiceImpl implements TemplateService {
  13.     private final TemplateMapper mapper;
  14.     @Override
  15.     public List<TemplateRespDto> list(TemplateReqDto param) {
  16.         return mapper.selectManySelective(param) // 可根据实际情况将实体做转换
  17.     }
  18. }

:::info 实现类中也只需要重写list方法体，将实际业务场景中需要处理的业务逻辑处理和查询方法写入其中，并不需要关心分页功能 :::

  1. @Slf4j // 同上
  2. @RestController // SpringBoot中注册Controller Bean的注解
  3. @RequiredArgsConstructor // 同上
  4. public class TemplateController {
  5.     public final TemplateService service;
  6.     /**
  7.      * 分页查询
  8.      *
  9.      * @param pageParam 分页查询参数
  10.      * @return 分页查询响应
  11.      */
  12.     @PostMapping(path = "page")
  13.     public PageInfo<Result> page(@RequestBody PageParam<Param> pageParam) {
  14.         return service.page(pageParam);
  15.     }
  16.     /**
  17.      * 集合查询
  18.      *
  19.      * @param listParam 集合查询参数
  20.      * @return 集合查询响应
  21.      */
  22.     @PostMapping(path = "list")
  23.     public List<Result> list(@RequestBody Param listParam) {
  24.         return service.list(listParam);
  25.     }
  26. }

:::info 最后编码Controller接口时，也只需要直接调用service.page即可，而请求参数直接用PageParam包装，将分页参数和业务参数分离，在前后端接口联调中，保持这种分离规范，可以很大程度上的降低沟通和开发成本 :::

FAQ

1、BaseService作为interface，page为什么可以声明方法体?

答：Java8中新特性之一就是为interface接口类增加了static/default方法，即声明方法后，其子类或实现都将默认具有这些方法，可以直接调用 而在此处为Page方法声明default是因为page函数只关注分页参数和分页响应，脱离了业务场景，方法体大相径庭，所以索性抽象定义出来，免去了其实现的复杂冗余过程

2、PageParam的声明有什么意义?实现IPage是为了什么?

答：PageParam是参考PageInfo编写的类(不确定往后PageHelper是否会封装此类) 编写此类的目的就是为了分离分页和业务数据，让开发者专注于业务的实现和开发，同时也是对分页查询API的一种规范，无论是请求还是响应都将分页相关的数据抽离出来，单独使用 而实现IPage则是因为IPage作为PageHelper内置的interface，在不了解它更多意义上的作用前，可以作为分页参数声明的一种规范，而IPage中也只声明了三个方法，分别是pageNum/pageSize/orderBy的Getter方法，另外在源码分析中，将会提到实现此接口更深层的意义

3、PageParam中除了常规的pageNum/pageSize，为什么还需要一个orderBy?

答：常规的分页查询中只需要pageNum/pageSize即可完成分页的目的，但是往往伴随着分页查询的还有筛选排序，而orderBy则是专注基于SQL的动态传参排序

4、orderBy如何使用?会有什么问题吗?

答：orderBy和pageNum/pageSize一样，都是Pagehelper通过MyBatis拦截器，在query查询中注入进去的，所以在前端传参时，orderBy参数应为数据库column desc/asc这种形式，多字段排序则可以用逗号(,)拼接，譬如：columnA desc,columnB，但是另外一方面又存在两个问题，第一就是大多数数据库表字段设计中，都会使用蛇形case命名，而非常规开发中的驼峰case命名，所以存在一层转换，而这种转换可以分配给前端传参时，也可以分配给后端接参时。第二就是这样赤裸裸的将排序字段暴露在接口中，会存在order by SQL注入的风险，所以在实际使用过程中，需要通过某些手段去校验和排查orderBy的传参是否合法，譬如用正则表达式匹配参数值只能含有order by语法中必要的值，例如字段名，desc or asc，不允许包含特殊字符/数据库关键字等

5、pageNum/pageSize一定需要给默认值吗?

答：通过阅读PageHelper源码，得知在Page查询参数为null时，它并不会赋予它们默认值，并不进行额外的处理，以至于导致分页失败，而给默认值，也是为了谨防前后端调试接口过程中可能会出现的各种意外

3、源码分析

首先看PageHelper.startPage(param)过程中发生了什么：

  1. public static <E> Page<E> startPage(Object params) {
  2.     Page<E> page = PageObjectUtil.getPageFromObject(params, true);
  3.     Page<E> oldPage = getLocalPage();
  4.     if (oldPage != null && oldPage.isOrderByOnly()) {
  5.         page.setOrderBy(oldPage.getOrderBy());
  6.     }
  7.     setLocalPage(page);
  8.     return page;
  9. }

这是PageHelper继承(extend)的抽象类PageMethod中的一个静态方法

再看代码第一行 Page<E> page = PageObjectUtil.getPageFromObject(params, true)发生了什么：

  1. public static <T> Page<T> getPageFromObject(Object params, boolean required) {
  2.     if (params == null) {
  3.         throw new PageException("无法获取分页查询参数!");
  4.     } else if (params instanceof IPage) {
  5.         IPage pageParams = (IPage)params;
  6.         Page page = null;
  7.         if (pageParams.getPageNum() != null && pageParams.getPageSize() != null) {
  8.             page = new Page(pageParams.getPageNum(), pageParams.getPageSize());
  9.         }
  10.         if (StringUtil.isNotEmpty(pageParams.getOrderBy())) {
  11.             if (page != null) {
  12.                 page.setOrderBy(pageParams.getOrderBy());
  13.             } else {
  14.                 page = new Page();
  15.                 page.setOrderBy(pageParams.getOrderBy());
  16.                 page.setOrderByOnly(true);
  17.             }
  18.         }
  19.         return page;
  20.     } else {
  21.         ... // 此处只截取了部分代码片段, 以上是较为重要的一块
  22.     }
  23. }

可以看到在此方法中，会先判断params是否为null，再而通过instanceof判断是否为IPage的子类或实现类 如果以上两个if/else 皆不满足，则PageHelper则会在省略贴出的代码中通过大量的反射代码来获取pageNum/pageSize以及orderBy。总所皆知，反射在Java中虽然广泛应用，并且作为语言独有特性之一，深受广大开发者的喜爱，但是反射在某种程度上，是需要性能成本的，甚至于现阶段很多主流的框架和技术，都在尽量减少反射的运用，以防止框架性能过差，被市场淘汰。那么到此为止，也终于解释并知道了为什么PageParam要实现IPage接口了，在此处的代码中可以直接通过接口获取到分页参数，而不需要通过有损性能的反射获取PageHelper需要的参数
继续看startPage中的后续代码：

  1. public abstract class PageMethod {
  2.     protected static final ThreadLocal<Page> LOCAL_PAGE = new ThreadLocal();
  3.     protected static boolean DEFAULT_COUNT = true;
  4.     public PageMethod() {
  5.     }
  6.     protected static void setLocalPage(Page page) {
  7.         LOCAL_PAGE.set(page);
  8.     }
  9.     public static <T> Page<T> getLocalPage() {
  10.         return (Page)LOCAL_PAGE.get();
  11.     }
  12.     ...
  13.     ...
  14. }

可以看到PageHelper继承的抽象类PageMethod中声明了一个Page的线程本地变量，而getLocalPage()则是为了获取当前线程中的Page而接下来if (oldPage != null && oldPage.isOrderByOnly())则是判断是否存在旧分页数据 此处的isOrderByOnly通过getPageFromObject()函数可以知道，当只存在orderBy参数时，即为true也就是说，当存在旧分页数据并且旧分页数据只有排序参数时，就将旧分页数据的排序参数列入新分页数据的排序参数 然后将新的分页数据page存入本地线程变量中 实际应用场景中，这种情况还是比较少，仅排序而不分页，所以某种角度上而言，仅当了解便好
接下来再看doSelectPageInfo(ISelect) 中发生了什么：

  1. public <E> PageInfo<E> doSelectPageInfo(ISelect select) {
  2.     select.doSelect();
  3.     return this.toPageInfo();
  4. }

可以看到，该方法的实现非常简单明了，就是通过注册声明ISelect接口由开发自定义集合查询方式并由它内部执行，随后便返回PageInfo实体 前面有提到，PageHelper基于MyBatis拦截器达到分页的目的，那么为什么此处的ISelect.doSelect()执行，就可以返回PageInfo实体呢? 实际上这便是拦截器的妙用所在，在select.doSelect()执行时，会触发PageHelper自定义的MyBatis查询拦截器，并通过解析SQL和SQL参数，根据数据库类型，进行分页，譬如MySQL的limit，Oracle的Rownum等，同时还会在定义的查询SQL之前，PageHelper会重新生成一条select count(*)的SQL率先执行，已达到它定义Page内置分页参数的目的

  1. @Intercepts({@Signature(
  2.     type = Executor.class,
  3.     method = "query",
  4.     args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}
  5. ), @Signature(
  6.     type = Executor.class,
  7.     method = "query",
  8.     args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class, CacheKey.class, BoundSql.class}
  9. )})
  10. public class PageInterceptor implements Interceptor {
  11.     private volatile Dialect dialect;
  12.     private String countSuffix = "_COUNT";
  13.     protected Cache<String, MappedStatement> msCountMap = null;
  14.     private String default_dialect_class = "com.github.pagehelper.PageHelper";
  15.     public PageInterceptor() {
  16.     }
  17.     public Object intercept(Invocation invocation) throws Throwable {
  18.     ...
  19.     ...
  20.     }
  21. }

以上便是PageHelper内置的自定义MyBatis拦截器。

拓展

PageHelper不仅有pageNum/pageSize/orderBy这几个参数，更还有pageSizeZero, reasonable参数等用以更进阶的分页查询定义。

四、总结

PageHelper作为GitHub上现在近10K的开源分页框架，也许代码深度和广度不及主流市场框架和技术，虽然在功能的实现和原理上，造轮子的难度不高，源码也很清晰，但是在很大程度上解决了很多基于MyBatis的分页技术难题，简化并提示了广大开发者的效率，这才是开发者们在开发的路上应该向往并为之拼搏的方向和道路。作为受益者，也不应当仅仅是对其进行基本的使用，开发之余，也应该关注一些框架的拓展，对框架的底层有一定程度上的了解，并为之拓展和优化