MyBatis-Plus实现分页查询两种方案详解

时间：2026-05-05 12:08

方案一：PageUtils 工具类分页（ThreadLocal 封装版） 1 方案概述在不少传统或存量项目中，你可能会遇到一个熟悉的“老朋友”：PageUtils startPage()。这通常是项目内部统一封装的分页工具类，其底层基于 MyBatis-Plus 的分页插件。它的最大魅力在于，通

方案一：PageUtils 工具类分页（ThreadLocal 封装版）

1. 方案概述

在不少传统或存量项目中，你可能会遇到一个熟悉的“老朋友”：PageUtils.startPage()。这通常是项目内部统一封装的分页工具类，其底层基于 MyBatis-Plus 的分页插件。它的最大魅力在于，通过 ThreadLocal 技术存储分页参数，实现了对业务代码的“零侵入”。对于不希望动刀原有逻辑的场景，它往往是首选。

MyBatis-Plus实现分页查询两种方案详解

2. 核心原理

当你在 Controller 层调用 startPage() 时，工具类会悄无声息地获取前端传来的页码和每页条数；
随后，MyBatis-Plus 的分页拦截器会精准拦截后续的 SQL 执行，并自动拼接上 LIMIT 语句；
最终，查询返回的普通 List 集合，会被工具类自动“包装”成一个标准的分页结果集，返回给前端。

整个过程，Service 和 Mapper 层完全感知不到分页的存在，仿佛什么都没发生。

3. 适用场景

项目已经存在一变钱成的、封装好的分页工具类。
核心诉求是不改动原有的 Mapper 或 Service 层代码。
追求快速实现分页功能，进行低成本的系统改造。

4. 完整代码示例

4.1 Controller 层

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import ja vax.annotation.Resource;
import ja va.util.List;

/**
 * 案件维度管理 Controller
 */
@RestController
@RequestMapping("/justice/case/dimension")
public class JusticeCaseDimensionController {

    @Resource
    private CaseDimensionContext caseDimensionContext;

    /**
     * 按范围查询案件聚合维度（账龄+批次号/被告）
     * 方案一：PageUtils 工具类分页
     */
    @GetMapping("/selectCaseDimensionByScope")
    public R selectCaseDimensionByScope(JusticeCaseDimensionQuery caseDimensionQuery) {
        // 1. 开启分页（核心：自动接收前端 page/pageSize 参数）
        PageUtils.startPage();
        
        // 2. 执行业务查询，返回普通 List 集合
        List justiceCaseDimensions = caseDimensionContext.selectCaseDimensionByScope(caseDimensionQuery);
        
        // 3. 工具类封装 List 为分页结果返回
        return R.page(justiceCaseDimensions);
    }
}

4.2 Service/Mapper 层

这里无需任何分页相关代码，保持原样，正常返回 List 集合即可。这正是该方案“无侵入性”的体现。

二、方案二：MyBatis-Plus 原生 IPage 分页（官方推荐）

1. 方案概述

如果说方案一是“民间智慧”，那么 IPage（或其实现类 Page）就是 MyBatis-Plus 框架官方钦定的分页对象。它通过方法参数和返回值来显式传递分页信息，代码意图清晰，结构规范，是新项目启动时的标准答案。

2. 核心原理

前端传递的 page、pageSize 参数，会被 SpringMVC 自动绑定并封装成一个 Page 对象；
将这个 Page 对象作为参数传入查询方法，MyBatis-Plus 便会心领神会地进行分页查询；
方法直接返回 IPage 对象，其中总条数、总页数、当前页数据等分页要素一应俱全，无需二次封装。

3. 适用场景

全新项目的开发，希望遵循官方最佳实践。
需要清晰、明确的分页参数传递路径，便于代码阅读和维护。
追求极简的代码结构，降低长期的维护成本。

4. 完整代码示例

4.1 Controller 层（业务接口）

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import ja vax.annotation.Resource;

/**
 * 案件维度管理 Controller
 */
@RestController
@RequestMapping("/justice/case/dimension")
public class JusticeCaseDimensionController {

    @Resource
    private CaseDimensionContext caseDimensionContext;

    /**
     * 按范围查询案件聚合维度（账龄+批次号/被告）
     * 方案二：原生 IPage 分页（官方推荐）
     */
    @GetMapping("/selectCaseDimensionByScope")
    public R> selectCaseDimensionByScope(
            // 分页参数：自动接收 page、pageSize
            Page page,
            JusticeCaseDimensionQuery caseDimensionQuery
    ) {
        // 1. 直接传入 Page 对象，返回 IPage 分页结果
        IPage pageResult = caseDimensionContext.selectCaseDimensionByScope(page, caseDimensionQuery);
        
        // 2. 直接返回原生分页对象
        return R.ok(pageResult);
    }
}

4.2 Service 层

/**
 * Service 层方法
 */
public IPage selectCaseDimensionByScope(Page page, JusticeCaseDimensionQuery query) {
    // 调用 Mapper，直接返回 IPage
    return baseMapper.selectCaseDimensionByScope(page, query);
}

4.3 Mapper 层

/**
 * Mapper 层方法
 */
IPage selectCaseDimensionByScope(Page page, @Param("query") JusticeCaseDimensionQuery query);

三、两种分页方案核心对比

对比维度	PageUtils 工具类分页	原生 IPage 分页
官方推荐度	非官方，项目自定义封装	✅ MyBatis-Plus 官方标准
代码侵入性	无侵入，无需修改原有接口	轻度侵入，需传入 Page 对象
代码简洁度	需手动开启分页 + 封装结果	一步到位，代码极简
分页信息	工具类自动封装	自带完整分页信息（总条数 / 总页数）
适用项目	老项目、存量系统改造	新项目、标准化开发
学习成本	低（直接调用工具方法）	低（原生对象，无额外学习）