MyBatis分页插件PageHelper的不同使用方式

在MyBatis生态中，高效、便捷地处理分页查询是一个常见的需求。PageHelper作为一款广受欢迎的分页插件，很好地解决了这个问题。它支持包括Oracle、MySQL、PostgreSQL在内的多达12种主流数据库，并且提供了多种灵活的分页调用方式，能够无缝集成到你的MyBatis项目中。

一、项目依赖

要开始使用PageHelper，首先需要在你的项目构建文件（如Ma ven的pom.xml）中添加以下依赖。请注意选择与你项目环境兼容的版本。

    com.github.pagehelper
    pagehelper
    6.1.1
    compile

二、分页插件的不同使用方式

PageHelper的设计非常灵活，开发者可以根据自己的编码习惯和项目结构选择最合适的一种。下面我们来逐一看看这几种主流用法。

第一种：Mapper接口调用（推荐）

这是最常用也最推荐的方式。通过在Service层或Mapper调用前执行一个静态方法即可。

//Mapper接口方式的调用，推荐这种使用方式。
PageHelper.startPage(1, 10);
List list = userMapper.selectIf(1);

这里有一个关键细节需要注意：分页效果只会作用于PageHelper.startPage方法之后紧接着的第一个MyBatis查询（Select）方法。后续的查询不会被分页。

第二种：使用RowBounds参数

这是一种较为原始的方式，直接在使用SqlSession执行查询时传入RowBounds对象。

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

第三种：offsetPage方法

这种方式与startPage类似，但它直接指定偏移量和每页大小，在某些场景下更直观。

PageHelper.offsetPage(0, 10);
List list = userMapper.selectIf(1);

第四种：参数方法调用

如果你希望将分页参数直接作为Mapper接口方法的参数传递，可以这样配置和使用。

//首先，在MyBatis配置中启用参数支持：supportMethodsArguments=true
//Mapper接口方法定义如下，无需在XML中处理pageNum和pageSize参数
public interface CountryMapper {
    List selectByPageNumSize(
            @Param("user") User user,
            @Param("pageNum") int pageNum,
            @Param("pageSize") int pageSize);
}
//调用时直接传入参数即可自动分页
List list = userMapper.selectByPageNumSize(user, 1, 10);

第五种：参数对象

这种方式将分页参数整合到查询对象实体中，当实体中的分页字段有值时，插件会自动识别并进行分页。

//假设User实体类中包含分页参数字段
public class User {
    //...其他字段
    private Integer pageNum; //参数名需与配置匹配
    private Integer pageSize;
}
//Mapper接口方法只需接收该实体
public interface CountryMapper {
    List selectByPageNumSize(User user);
}
//当user中的pageNum和pageSize不为null时，查询会自动分页
List list = userMapper.selectByPageNumSize(user);

三、重要提示与避坑指南

为了让PageHelper稳定工作，避免一些常见的陷阱，以下几点需要特别留意：

1. 作用范围限制：正如前面提到的，分页仅对PageHelper.startPage或offsetPage方法后的第一个查询语句生效。这是一个重要的设计约定。

2. 避免多个分页插件：在一个项目中，不要同时配置多个分页插件（例如，既在mybatis-config.xml中配置，又在Spring配置文件中配置）。这会导致不可预知的行为。

3. 不支持`FOR UPDATE`语句：对于使用了FOR UPDATE进行锁定的SQL，分页插件不支持。执行时会抛出运行时异常。这类涉及锁的查询，通常建议手动控制分页逻辑。

4. 不支持嵌套结果映射：当MyBatis使用嵌套结果映射（association/collection）时，结果集会被“折叠”。这会导致分页插件计算的总记录数不准确，因此在这种情况下也无法保证分页正确。

四、实战代码示例

理论说再多，不如看代码来得直观。下面通过两个典型的后端示例，展示PageHelper如何融入实际开发。

示例一：使用内置PageInfo

这是最标准的用法。在Service层启动分页，查询后使用PageHelper提供的PageInfo类来包装结果，它包含了分页所需的全部元数据。

Controller 层接口：

    @PostMapping("/queryList")
    public ResponseEntity> queryList(@RequestBody ReconcileOrderRequest request) {
        List orderList = operateReconcileService.queryList(request);
        PageInfo pageInfo = new PageInfo<>(orderList);
        return ResponseEntity.ok().body(pageInfo);
    }

Service 方法：

	public List queryList(ReconcileOrderRequest request) {
        ReconcileOrderPageDto orderPageDto = buildReconcileOrderPageDto(request);
        //分页查询
        PageHelper.startPage(request.getPage(), request.getPageSize());
        List pageReconcile = operateOrderMapper.selectOrderByReconcileTime(orderPageDto);
        return pageReconcile;
    }

示例二：自定义分页响应类

有时，项目对API响应格式有统一要求，PageInfo的字段可能不满足需求。这时，我们可以自定义一个分页类，其核心是能够识别并转换PageHelper返回的Page对象。

import com.github.pagehelper.Page;
import lombok.ToString;
import ja va.util.List;

@ToString
public class MyPageInfo{
    /**
     * 总条数
     */
    private int total;
    /**
     * 当前页条数
     */
    private int size;
    /**
     * 每页条数
     */
    private int pageSize;
    /**
     * 当前页码
     */
    private int pageNum;
    /**
     * 分页数据
     */
    private List list;

    // 核心构造方法：自动从Page对象提取分页信息
    public MyPageInfo(List data) {
        this.list = data;
        if (data instanceof Page) {
            Page page = (Page) data;
            this.pageNum = page.getPageNum();
            this.pageSize = page.getPageSize();
            this.size = page.size();
            this.total = (int) page.getTotal();
        } else if (data != null) {
            // 若非分页查询结果，则按单页全部数据处理
            this.pageNum = 1;
            this.pageSize = data.size();
            this.size = data.size();
            this.total = data.size();
        }
    }
    // 省略getter/setter...
}

这个自定义的MyPageInfo类不仅包含了基本的分页数据，你还可以根据项目规范，轻松地增加诸如success（标识请求成功与否）、errorMessage（错误信息）等通用字段。

使用自定义类后，Controller层的代码可以调整为：

    @PostMapping("/queryList")
    public ResponseEntity> queryList(@RequestBody ReconcileOrderRequest request) {
        List orderList = operateReconcileService.queryList(request);
        MyPageInfo myPageInfo = new MyPageInfo<>(orderList);
        return ResponseEntity.ok().body(myPageInfo);
    }

这样一来，后端返回的分页数据结构就完全掌控在自己手中，能够更好地适配前端的需求或统一的响应体格式。