轻松实现MyBatis分页查询：PageHelper实战教程

在日常的Java后端开发中，分页查询是业务系统里高频出现的需求，手动编写分页SQL不仅繁琐，还容易因不同数据库方言（如MySQL、Oracle）产生兼容问题。MyBatis PageHelper作为一款轻量级的分页插件，能极大简化分页开发流程，本文结合实际代码案例，带你快速掌握PageHelper的配置与使用。

一、PageHelper简介

PageHelper是MyBatis生态中非常流行的分页插件，支持多种数据库（MySQL、Oracle、SQL Server等），通过拦截MyBatis的执行流程，自动拼接分页SQL，开发者无需关注底层分页逻辑，只需调用简单的API即可实现分页功能。

项目地址：https://github.com/pagehelper-org/Mybatis-PageHelper

二、PageHelper配置（Spring Boot环境）

首先需要在Spring Boot项目中完成PageHelper的配置，确保插件能正常生效。以下是基于Java配置类的实现方式：

1. 核心配置类

import com.github.pagehelper.PageInterceptor;
import org.apache.ibatis.plugin.Interceptor;
import org.apache.ibatis.session.Configuration;
import org.mybatis.spring.boot.autoconfigure.ConfigurationCustomizer;
import org.springframework.context.annotation.Bean;
import java.util.Properties;

@org.springframework.context.annotation.Configuration
public class PageHelperConfig {

    @Bean
    public ConfigurationCustomizer configurationCustomizer() {
        return new ConfigurationCustomizer() {
            @Override
            public void customize(Configuration configuration) {
                // 创建PageHelper拦截器
                PageInterceptor pageInterceptor = new PageInterceptor();
                // 设置PageHelper属性
                Properties properties = new Properties();
                // 指定数据库方言（此处为MySQL）
                properties.setProperty("helperDialect", "mysql");
                // 启用合理化分页：页码<=0时查第一页，页码>总页数时查最后一页
                properties.setProperty("reasonable", "true");
                // 支持通过Mapper方法参数传递分页参数
                properties.setProperty("supportMethodsArguments", "true");
                // 设置count查询的参数名
                properties.setProperty("params", "count=countSql");
                pageInterceptor.setProperties(properties);
                // 将拦截器添加到MyBatis配置中
                configuration.addInterceptor(pageInterceptor);
            }
        };
    }
}

2. 配置参数说明

参数名	作用
helperDialect	指定数据库方言，PageHelper会根据方言自动生成对应分页SQL
reasonable	分页合理化，避免因页码错误导致查询失败
supportMethodsArguments	允许通过Mapper方法的参数传递分页参数（如pageNum、pageSize）
params	配置分页参数映射，count=countSql表示使用PageHelper自带的count查询逻辑

三、PageHelper实战使用

配置完成后，即可在业务层快速实现分页查询，以下是文章列表分页的实战案例：

1. 业务层分页实现

@Override
public PageBean<Article> list(Integer pageNum, Integer pageSize, Integer categoryId, String state) {
    //1.创建分页结果封装对象
    PageBean<Article> pb = new PageBean<>();

    //2.开启分页查询：PageHelper核心API，紧跟其后的第一个查询会被分页
    PageHelper.startPage(pageNum,pageSize);

    //3.调用Mapper查询数据（无需手动拼接分页SQL）
    // ThreadLocalUtil.get()：获取当前登录用户信息（业务场景）
    Map<String,Object> map = ThreadLocalUtil.get();
    Integer userId = (Integer) map.get("id");
    // 普通的列表查询，PageHelper会自动拦截并添加分页条件
    List<Article> as = articleMapper.list(userId,categoryId,state);
    
    //4.获取分页结果：PageHelper会将查询结果封装为Page对象
    Page<Article> p = (Page<Article>) as;

    //5.填充分页数据到自定义PageBean
    pb.setTotal(p.getTotal()); // 总记录数
    pb.setItems(p.getResult()); // 当前页数据列表
    return pb;
}

2. 核心步骤说明

开启分页：PageHelper.startPage(pageNum, pageSize) 是核心方法，该方法会拦截其后的第一个MyBatis查询，自动添加LIMIT（MySQL）或对应的分页语法。
执行查询：调用Mapper的普通列表查询方法，无需修改SQL，PageHelper会自动处理分页逻辑。
获取分页数据：查询结果会被封装为Page对象，通过getTotal()获取总记录数，getResult()获取当前页数据。
封装返回：将分页数据封装到自定义的PageBean（业务通用分页对象）中，返回给前端。

3. 自定义PageBean（参考）

通常我们会封装通用的分页返回对象，示例如下：

public class PageBean<T> {
    // 总记录数
    private Long total;
    // 当前页数据列表
    private List<T> items;

    // 省略getter/setter
}

四、PageHelper使用注意事项

分页范围：PageHelper.startPage() 仅对其后的第一个MyBatis查询生效，若有多个查询，需在每个查询前单独调用。
线程安全：PageHelper通过ThreadLocal保证分页参数的线程安全，无需担心多线程环境下的参数混乱。
count查询：PageHelper默认会自动执行count查询获取总记录数，若无需总记录数，可通过PageHelper.startPage(pageNum, pageSize, false)关闭。
数据库兼容：只需修改helperDialect参数，即可适配不同数据库，无需修改业务代码。

五、总结

PageHelper凭借其简洁的API、强大的功能和良好的兼容性，成为MyBatis分页的首选方案。通过本文的配置和实战案例，你可以快速在项目中集成PageHelper，告别繁琐的手动分页SQL，大幅提升开发效率。

如果你在使用过程中有其他问题，可参考PageHelper官方仓库：https://github.com/pagehelper-org/Mybatis-PageHelper，获取更详细的文档和示例。