SpringBoot整合PageHelper实现分页查询功能

一、为什么需要分页？

在数据量面前，一个不争的事实是——如果不做分页，应用就得一次性地把所有满足条件的数据都查出来、渲染出来。后果是什么？查询越来越慢，页面越来越卡，直到某一天，用户等得不耐烦了直接关掉页面。

分页查询，是解决这个问题的经典方案。这篇文章就专注于一个场景：在 Spring Boot + MyBatis 项目中，如何用 PageHelper 快速落地一个高效、可用的分页功能。

二、PageHelper 简介

简单来说，PageHelper 是 MyBatis 生态里一个相当成熟的分页插件，它的核心卖点就在这几个字上：操作简单、自动化、易集成。

它的典型优势在于：

• 操作简单：查询前只加一行 startPage() 就行，原有的 SQL 一句不用动。
• 自动拦截：它会自动帮你拦截 SQL，拼接出正确的 LIMIT 语句，顺便完成 count 查询。说白了，就是替你写了那条 LIMIT 语句。
• 开箱即用：自带 Spring Boot Starter，引入依赖就能干活。

三、环境搭建

先把依赖加到 pom.xml 里：

    com.github.pagehelper
    pagehelper-spring-boot-starter
    1.4.6

为了让前后端的数据交互有统一规范，我们先定义一个通用的分页结果类 PageBean：

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

其中 total 告诉前端一共有多少条数据，用来算总页数；items 就是当前页要展示的具体数据。

四、核心使用方式

真的只需要一行代码：

// 开启分页查询
PageHelper.startPage(pageNum, pageSize);
// 直接进入 Mapper 层，PageHelper 会自动插入 LIMIT 语句
List
 as = articleMapper.list(userid, categoryId, state);

这背后的原理就是把分页参数塞进 ThreadLocal，等下次查询时拦截器自动识别并处理。

五、实战：文章列表分页查询

下面以项目中的文章列表为例，完整跑一遍从 Controller 到 Mapper 的全链路。

Controller 层

接收前端的分页参数和查询条件：

@GetMapping
public Result> list(
    Integer pageNum,
    Integer pageSize,
    @RequestParam(required = false) Integer categoryId,
    @RequestParam(required = false) String state
) {
    PageBean
 pb = articleService.list(pageNum, pageSize, categoryId, state);
    return Result.success(pb);
}

几个关键点：pageNum 是当前页码，从 1 开始；pageSize 是每页条数；categoryId 和 state 是可选的业务查询条件，用 required = false 来标记。注意控制器的返回值类型要跟 Result 统一。

Service 层

这里是分页逻辑的核心所在：

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

    // 2. 开启分页查询
    PageHelper.startPage(pageNum, pageSize);

    // 3. 调用 Mapper 查询（此时返回的 List 实际上是 Page 类型）
    Map map = ThreadLocalUtil.get();
    Integer userid = (Integer) map.get("id");
    List
 as = articleMapper.list(userid, categoryId, state);

    // 4. 强转为 Page 对象，获取分页信息
    Page
 p = (Page
) as;

    // 5. 封装结果
    pb.setTotal(p.getTotal());
    pb.setItems(p.getResult());
    return pb;
}

第 4 步的强转是为了拿到 Page 类里封装好的分页信息——这个 Page 类就是 PageHelper 自己提供的。

Mapper 层

这里基本不用动，该怎么写就怎么写：

    select * from article
    
        
            category_id = #{categoryId}
        
        
            and state = #{state}
        
        and create_user = #{userid}
    

PageHelper 会在后台悄悄地做两件事：

• 先执行一条 SELECT COUNT(*) FROM article WHERE ... 来拿总记录数。
• 再在原 SQL 后面拼接 LIMIT offset, pageSize，完成分页查询。

六、PageHelper 工作原理（简述）

一句话概括：PageHelper 通过 MyBatis 的 Interceptor（拦截器）机制，在执行真正的查询之前对 SQL 进行改写。startPage() 方法把分页参数塞进 ThreadLocal，确保同一线程中的下一次查询被拦截处理。这本质上是 AOP 的思想，但并不是通过 Spring Boot 的 AOP 去实现的，而是直接基于 MyBatis 自身的拦截器机制。

七、总结

回过头来看，通过 PageHelper，我们在 Spring Boot 项目里几乎是以零侵入的方式完成了分页功能：

• 加一个依赖：pagehelper-spring-boot-starter
• 封装一个结果类：PageBean
• 一行代码开启分页：PageHelper.startPage(pageNum, pageSize)
• 正常写查询：Mapper 的 SQL 一句不用动
• 强转获取分页信息：Page 类型的转换
• 提取结果：通过 Page.getTotal() 和 Page.getResult() 拿到数据

这种设计让分页逻辑和业务代码完全解耦，在日常开发中，算是非常推荐的一种方案了。