MyBatis PageHelper 使用手册

MyBatis 分页插件，最方便使用的分页插件，支持多种数据库

📖 产品概述

MyBatis PageHelper 是一个强大的 MyBatis 分页插件，提供简单易用的分页功能。它支持多种数据库，包括 Oracle、MySQL、MariaDB、SQLite、H2、PostgreSQL 等主流数据库，以及更多数据库类型。

🚀 快速开始

1. Maven 依赖引入

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

2. Gradle 依赖

dependencies {
    compile 'com.github.pagehelper:pagehelper:最新版本'
}

3. Spring Boot 集成

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

⚙️ 配置说明

1. MyBatis 配置

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

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

2. 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>

3. Spring Boot 配置

# application.properties
pagehelper.propertyName=propertyValue
pagehelper.reasonable=false
pagehelper.defaultCount=true

# application.yml
pagehelper:
  propertyName: propertyValue
  reasonable: false
  defaultCount: true # 使用 RowBounds 分页会执行 count 查询

🔧 核心参数配置

参数	默认值	说明
helperDialect	-	分页插件方言，支持多种数据库
dialectAlias	-	数据库方言别名配置
offsetAsPageNum	false	offsetAsPageNum=true 时，RowBounds 的 offset 会当成 pageNum 使用
rowBoundsWithCount	false	RowBounds 是否进行 count 查询
pageSizeZero	false	pageSize=0 时返回所有数据
reasonable	false	分页合理化参数
params	-	支持 Mapper 接口参数来传递分页参数
supportMethodsArguments	false	支持通过 Mapper 接口参数来传递分页参数
autoRuntimeDialect	false	自动识别数据库方言

💻 使用方法

1. 基础分页

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

// PageHelper.startPage 方式
PageHelper.startPage(1, 10);
List<User> list = userMapper.selectIf(1);

// PageHelper.offsetPage 方式
PageHelper.offsetPage(0, 10);
List<User> list = userMapper.selectIf(1);

2. 复杂分页

// 使用 ISelect 接口
Page<User> page = PageHelper.startPage(1, 10).doSelectPage(newISelect() {
    @Override
    publicvoiddoSelect() {
        userMapper.selectGroupBy();
    }
});

// Lambda 写法 (jdk8)
Page<User> page = PageHelper.startPage(1, 10).doSelectPage(() -> userMapper.selectGroupBy());

// 返回 PageInfo
PageInfopage= PageHelper.startPage(1, 10).doSelectPageInfo(() -> userMapper.selectGroupBy());

// 返回 count
longtotal= PageHelper.count(() -> userMapper.selectLike(user));

3. 方法参数支持

开启 supportMethodsArguments=true 后，可以直接在 Mapper 方法中使用分页参数：

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

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

4. 线程安全使用

// 在 try-finally 中使用，确保清理
try {
    PageHelper.startPage(1, 10);
    List<User> list = userMapper.selectAll();
    // 处理结果
} finally {
    PageHelper.clearPage();
}

📊 分页结果处理

1. PageInfo 对象

PageHelper.startPage(1, 10);
List<User> list = userMapper.selectAll();
PageInfo pageInfo = new PageInfo(list);

// 获取分页信息
pageInfo.getPageNum();      // 当前页
pageInfo.getPageSize();     // 每页大小
pageInfo.getTotal();        // 总记录数
pageInfo.getPages();        // 总页数
pageInfo.isIsFirstPage();   // 是否为第一页
pageInfo.isIsLastPage();    // 是否为最后一页

2. Page 对象

Page<User> page = PageHelper.startPage(1, 10).doSelectPage(() -> userMapper.selectAll());
page.getTotal();        // 总数
page.getPages();        // 总页数
page.getPageNum();      // 当前页
page.getPageSize();     // 页面大小

⚠️ 重要注意事项

1. 调用位置限制

• • PageHelper.startPage() 方法调用必须紧跟在 MyBatis 查询方法之前

• • 不要在事务中混用不同类型的查询

2. 更新操作注意事项

• • 分页插件只对查询有效

• • 对于 for update 语句，不要使用分页插件

• • 在同一个方法中，如果先进行 update 操作再查询，需要特别注意

3. Spring 集成注意

• • 在 Spring 中使用时，要确保配置正确

• • 使用 try-finally 块确保页面清理

🔍 高级功能

1. 自定义方言

// 注册自定义方言
registerDialectAlias("custom", CustomDialect.class);

2. 自动运行时方言

autoRuntimeDialect=true

3. 聚合查询支持

// 聚合查询分页
PageHelper.startPage(1, 10);
List<Map<String, Object>> list = userMapper.selectGroupByDepartment();

🌟 核心优势

1. 1. 简单易用：一行代码实现分页

2. 2. 数据库兼容：支持多种主流数据库

3. 3. 功能强大：支持复杂查询分页

4. 4. 性能优秀：智能 count 查询优化

5. 5. 线程安全：内置线程安全机制

6. 6. 灵活配置：丰富的参数配置选项

📚 更多资源

• • GitHub 项目地址

• • 详细文档

• • 更新日志

💡 温馨提示：在生产环境中使用时，请根据实际需求合理配置参数，确保分页性能和用户体验的最优化。