MyBatis 分页插件 PageHelper

MyBatis 分页插件 PageHelper 详细介绍

PageHelper 是 MyBatis 的一个开源分页插件，它提供了简单易用的分页功能，支持多种数据库，能够大大简化分页查询的开发工作。

一、PageHelper 主要特性

1. 支持多种数据库：MySQL、Oracle、DB2、PostgreSQL、SQLite 等
2. 支持多种分页方式：物理分页和内存分页
3. 支持多种调用方式：支持多种调用方式，包括直接使用 PageHelper 方法或使用拦截器
4. 零侵入：无需修改现有查询逻辑
5. 支持多种参数传递方式：支持多种参数传递方式，包括使用 RowBounds 和 Page 参数
6. 支持 PageInfo 封装：提供 PageInfo 类对分页结果进行封装

二、PageHelper 使用步骤

1. 添加依赖

Maven 项目添加依赖：

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

2. 配置插件

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

<plugins>
    <plugin interceptor="com.github.pagehelper.PageInterceptor">
        <!-- 配置数据库方言 -->
        <property name="helperDialect" value="mysql"/>
        <!-- 合理化分页参数 -->
        <property name="reasonable" value="true"/>
        <!-- 支持通过 Mapper 接口参数来传递分页参数 -->
        <property name="supportMethodsArguments" value="true"/>
        <!-- 分页参数映射 -->
        <property name="params" value="count=countSql"/>
    </plugin>
</plugins>

或者在 Spring Boot 中通过 application.properties 配置：

# 分页插件配置
pagehelper.helper-dialect=mysql
pagehelper.reasonable=true
pagehelper.support-methods-arguments=true
pagehelper.params=count=countSql

3. 基本使用方法

// 第一种调用方式：在查询前调用
PageHelper.startPage(1, 10); // 第1页，每页10条
List<User> users = userMapper.selectAll();

// 第二种调用方式：使用PageInfo
PageHelper.startPage(2, 5);
List<User> users = userMapper.selectAll();
PageInfo<User> pageInfo = new PageInfo<>(users);

// 第三种调用方式：使用Lambda
PageInfo<User> pageInfo = PageHelper.startPage(1, 10)
    .doSelectPageInfo(() -> userMapper.selectAll());

   public PageResult query(CategoryPageQueryDTO categoryPageQueryDTO) {
        PageHelper.startPage(categoryPageQueryDTO.getPage(),categoryPageQueryDTO.getPageSize());
        List<Category> categoryList = categoryMapper.query(categoryPageQueryDTO);
        Page<Category> page= (Page<Category>) categoryList;
        return new PageResult(page.getTotal(),page.getResult());
    }

三、PageHelper 核心 API

1. PageHelper 类

• startPage(int pageNum, int pageSize)：开始分页
• startPage(int pageNum, int pageSize, boolean count)：开始分页，是否进行count查询
• offsetPage(int offset, int limit)：使用offset和limit分页
• doSelectPage(ISelect select)：执行分页查询
• doSelectPageInfo(ISelect select)：执行分页查询并返回PageInfo

2. PageInfo 类

• getList()：获取查询结果
• getTotal()：获取总记录数
• getPages()：获取总页数
• getPageNum()：获取当前页码
• getPageSize()：获取每页显示数量
• isFirstPage()：是否第一页
• isLastPage()：是否最后一页
• hasPreviousPage()：是否有上一页
• hasNextPage()：是否有下一页

四、高级用法

1. 排序支持

// 使用排序
PageHelper.startPage(1, 10, "id desc");
List<User> users = userMapper.selectAll();

// 或者
PageHelper.startPage(1, 10)
    .setOrderBy("id desc");
List<User> users = userMapper.selectAll();

2. 复杂参数查询

// 如果查询方法有多个参数，可以使用Map或@Param注解
Map<String, Object> params = new HashMap<>();
params.put("name", "test");
PageHelper.startPage(1, 10);
List<User> users = userMapper.selectByParams(params);

3. 分页插件原理

PageHelper 通过 MyBatis 的拦截器机制，在执行 SQL 前对 SQL 进行拦截和修改，添加分页相关的语句。

对于 MySQL：

原始SQL: select * from user
分页SQL: select * from user limit 0,10

对于 Oracle：

原始SQL: select * from user
分页SQL: select * from (select tmp.*, rownum row_id from (select * from user) tmp where rownum <= 10) where row_id > 0

五、常见问题

1. 分页不生效：

   • 确保 PageHelper.startPage() 紧跟在查询方法前调用
   • 确保没有在配置中禁用分页插件

2. 总数为-1：

   • 可能是没有执行 count 查询，检查是否设置了 pageSizeZero=true

3. 性能问题：

   • 对于大数据量表，count 查询可能较慢，可以考虑缓存总数

4. 多数据源问题：

   • 如果使用多数据源，需要为每个数据源配置不同的 helperDialect

六、最佳实践

1. 在 Service 层进行分页：不要在 Controller 中直接调用 PageHelper
2. 合理设置 pageSize：避免单页数据量过大
3. 使用 PageInfo 返回结果：便于前端处理分页信息
4. 复杂查询优化：对于复杂查询，考虑自定义 count 查询

PageHelper 是 MyBatis 生态中最流行的分页插件之一，合理使用可以大大提高开发效率，减少重复的分页代码编写。