MyBatis-PageHelper分页插件使用指南

一、项目介绍

MyBatis-PageHelper是一款优秀的MyBatis分页插件，它能够以极简的方式实现MyBatis物理分页功能。该插件支持多种数据库，包括MySQL、Oracle、PostgreSQL等主流数据库，并且可以与Spring、Spring Boot等框架无缝集成。

二、安装配置

1. 依赖引入

Maven项目

在pom.xml中添加以下依赖：

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

Spring Boot项目

使用starter可以简化配置：

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

2. 配置方式

MyBatis原生配置

在mybatis-config.xml中添加插件配置：

<plugins>
    <plugin interceptor="com.github.pagehelper.PageInterceptor">
        <!-- 参数配置 -->
        <property name="param1" value="value1"/>
    </plugin>
</plugins>

Spring配置

在Spring的applicationContext.xml中配置：

<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="plugins">
        <array>
            <bean class="com.github.pagehelper.PageInterceptor">
                <property name="properties">
                    <value>
                        param1=value1
                    </value>
                </property>
            </bean>
        </array>
    </property>
</bean>

Spring Boot配置

Spring Boot项目支持properties或yaml格式的配置：

# application.properties
pagehelper.helperDialect=mysql
pagehelper.reasonable=true
pagehelper.supportMethodsArguments=true

三、核心功能使用

1. 基本分页查询

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

// 第二种方式：使用PageHelper.offsetPage方法
PageHelper.offsetPage(0, 10); // 从第0条开始，取10条
List<User> users = userMapper.selectAll();

2. 获取分页信息

PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();

// 方式一：使用PageInfo包装结果
PageInfo<User> pageInfo = new PageInfo<>(users);
System.out.println("总记录数：" + pageInfo.getTotal());
System.out.println("总页数：" + pageInfo.getPages());

// 方式二：直接使用Page对象
Page<User> page = (Page<User>) users;
System.out.println("当前页：" + page.getPageNum());
System.out.println("每页数量：" + page.getPageSize());

3. 复杂查询分页

// 带条件的分页查询
PageHelper.startPage(2, 5, "id desc"); // 第2页，每页5条，按id降序
Example example = new Example(User.class);
example.createCriteria().andLike("name", "%张%");
List<User> users = userMapper.selectByExample(example);

四、高级特性

1. 多数据源支持

通过配置autoRuntimeDialect=true可以实现运行时自动识别不同数据源的方言：

pagehelper.autoRuntimeDialect=true
pagehelper.closeConn=false

2. 安全调用检查

开启debug模式可以检查不安全的分页调用：

pagehelper.debug=true

3. 自定义分页逻辑

实现Dialect接口可以自定义分页逻辑：

public class CustomDialect extends AbstractHelperDialect {
    // 实现自定义分页逻辑
}

然后在配置中指定：

pagehelper.dialect=com.example.CustomDialect

五、最佳实践

1. 合理设置reasonable参数：当设置为true时，会自动修正不合法的页码（如负数会返回第一页，超过总页数会返回最后一页）

2. 使用PageInfo简化分页信息获取：PageInfo提供了丰富的分页信息，包括页码导航等

3. 注意分页顺序：PageHelper.startPage()必须在查询方法调用前执行

4. 复杂SQL处理：对于包含子查询、UNION等复杂SQL，建议使用/*keep orderby*/注解保留排序

5. 性能优化：对于大数据量分页，建议使用countColumn指定优化count查询

六、常见问题

1. 分页失效：检查是否在查询方法前调用了startPage方法

2. 总记录数不准确：检查SQL是否包含GROUP BY等影响行数的操作

3. 排序失效：检查是否在PageHelper.startPage()中指定了排序条件

4. 多数据源问题：确保正确配置了autoRuntimeDialect和closeConn参数

通过合理配置和使用MyBatis-PageHelper，可以大大简化分页功能的开发，提高开发效率和代码可维护性。