MyBatis-PageHelper分页插件使用完全指南

MyBatis-PageHelper分页插件使用完全指南

Mybatis-PageHelper Mybatis通用分页插件 项目地址: https://gitcode.com/gh_mirrors/my/Mybatis-PageHelper

一、项目概述

MyBatis-PageHelper 是 MyBatis 框架的一款强大分页插件，它通过拦截器机制实现了对 MyBatis 查询的物理分页功能。该插件支持多种数据库方言，提供了简洁易用的 API，能够显著简化分页查询的开发工作。

二、环境准备

1. 依赖引入

Maven 项目配置

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

Spring Boot 项目配置

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

三、插件配置详解

1. 基本配置方式

MyBatis XML 配置方式

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

Spring XML 配置方式

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

Spring Boot 配置方式

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

2. 核心参数解析

| 参数名 | 默认值 | 说明 | |--------|--------|------| | helperDialect | 自动检测 | 指定数据库方言 | | reasonable | false | 分页合理化 | | pageSizeZero | false | 当pageSize=0时返回全部结果 | | supportMethodsArguments | false | 支持通过Mapper接口参数传递分页参数 | | autoRuntimeDialect | false | 多数据源运行时自动识别方言 | | closeConn | true | 自动关闭获取的连接 |

四、使用方式详解

1. 基础使用方式

方式一：RowBounds方式

List<User> list = sqlSession.selectList("x.y.selectIf", null, new RowBounds(1, 10));

方式二：PageHelper.startPage方式（推荐）

// 获取第1页，10条内容
PageHelper.startPage(1, 10);
List<User> list = userMapper.selectIf(1);
// 获取分页信息
PageInfo<User> pageInfo = new PageInfo<>(list);

2. 高级使用方式

参数传递方式

public interface UserMapper {
    List<User> selectByPageNumSize(
        @Param("user") User user,
        @Param("pageNum") int pageNum,
        @Param("pageSize") int pageSize);
}

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

Lambda表达式方式

// JDK8+ 推荐用法
Page<User> page = PageHelper.startPage(1, 10)
    .doSelectPage(() -> userMapper.selectGroupBy());
    
// 获取总数
long total = PageHelper.count(() -> userMapper.selectLike(user));

五、最佳实践与注意事项

1. 安全调用规范

正确示例：

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

错误示例：

PageHelper.startPage(1, 10);
List<User> list;
if(param1 != null){
    list = userMapper.selectIf(param1);
} else {
    list = new ArrayList<User>();
}

2. 多数据源配置建议

对于多数据源环境，建议配置：

pagehelper.autoRuntimeDialect=true
pagehelper.closeConn=false  # 根据实际数据源特性决定

3. 性能优化建议

1. 对于复杂查询，建议手动编写count查询
2. 合理配置countSuffix参数优化count查询
3. 使用boundSqlInterceptors对SQL进行优化处理

六、常见问题解决方案

问题1：分页失效

可能原因：

• PageHelper调用与查询方法不在同一线程
• 配置参数不正确

解决方案：

1. 确保PageHelper.startPage()紧邻查询方法
2. 检查分页插件是否配置正确

问题2：排序失效

解决方案： 配置keepOrderBy=true保留排序语句

问题3：多数据源分页异常

解决方案：

1. 配置autoRuntimeDialect=true
2. 根据数据源特性设置closeConn参数

七、总结

MyBatis-PageHelper 作为 MyBatis 生态中最受欢迎的分页插件，通过本文的详细介绍，开发者可以掌握：

1. 多种环境下的正确配置方式
2. 各种使用场景下的最佳实践
3. 常见问题的排查与解决方法
4. 性能优化的关键参数配置

合理使用该插件可以显著提升开发效率，同时保证分页查询的性能和稳定性。

Mybatis-PageHelper Mybatis通用分页插件 项目地址: https://gitcode.com/gh_mirrors/my/Mybatis-PageHelper