MyBatis Plus分页功能原理与最佳实践-代码聚汇网

1. MyBatis Plus 分页功能深度解析

作为一名长期使用 MyBatis Plus 进行企业级开发的工程师，我发现分页功能是日常开发中使用频率最高却又最容易出错的特性之一。很多开发者在使用过程中都会遇到各种问题，其中最典型的就是分页插件不生效的情况。今天我就从底层原理到实际应用，带大家彻底掌握 MyBatis Plus 的分页机制。

1.1 分页插件的核心工作原理

MyBatis Plus 的分页功能本质上是通过拦截器实现的。当我们在代码中调用 selectPage() 方法时，分页拦截器会按照以下步骤工作：

拦截 SQL 语句：拦截器会捕获你执行的查询 SQL
生成 COUNT 查询：自动生成对应的 SELECT COUNT(*) 语句用于计算总记录数
改写原始 SQL：将原始查询语句添加 LIMIT 子句
执行双重查询：先执行 COUNT 查询获取总数，再执行分页查询获取当前页数据
封装结果：将查询结果封装到 IPage 对象中返回

这个过程中最关键的环节就是拦截器的注册。如果没有正确配置拦截器，MyBatis Plus 就无法对 SQL 进行拦截和改写，自然也就无法实现分页功能。

1.2 新旧版本配置差异

在 MyBatis Plus 3.4.0 版本之前，分页插件是通过 PaginationInterceptor 类实现的。但从 3.4.0 版本开始，MyBatis Plus 引入了新的拦截器机制，改用 MybatisPlusInterceptor 作为统一的拦截器入口，并通过添加内部拦截器的方式配置各种功能。

新旧版本配置对比：

java复制// 旧版配置 (3.4.0之前)
@Bean
public PaginationInterceptor paginationInterceptor() {
    return new PaginationInterceptor();
}

// 新版配置 (3.4.0之后)
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
    return interceptor;
}

重要提示：如果你在项目中同时配置了新旧两种拦截器，可能会导致分页功能异常。建议统一使用新版配置方式。

2. 完整分页实现流程

2.1 基础环境准备

在开始实现分页功能前，请确保你的项目已经正确集成了 MyBatis Plus。基本的依赖配置如下：

xml复制<!-- pom.xml -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

2.2 分页插件配置详解

让我们更深入地看一下分页插件的配置选项。除了基本的数据库类型配置外，PaginationInnerInterceptor 还提供了多个可定制化的参数：

java复制@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    
    PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor(DbType.MYSQL);
    // 设置请求的页面大于最大页后操作，true调回到首页，false继续请求
    paginationInterceptor.setOverflow(false);
    // 设置单页分页条数限制
    paginationInterceptor.setMaxLimit(500L);
    
    interceptor.addInnerInterceptor(paginationInterceptor);
    return interceptor;
}

配置参数说明：

DbType：指定数据库类型，支持 MySQL、Oracle、PostgreSQL 等主流数据库
overflow：当请求页码超过总页数时的处理策略
maxLimit：单页最大记录数限制，防止恶意请求大量数据

2.3 分页查询的多种使用方式

2.3.1 基础分页查询

最基本的用法是使用 selectPage 方法：

java复制Page<User> page = new Page<>(1, 10); // 当前页，每页大小
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.like("name", "张");
IPage<User> userPage = userMapper.selectPage(page, wrapper);

2.3.2 自定义 SQL 分页

对于复杂的查询，你可能需要在 XML 中编写自定义 SQL，这时可以使用 selectPage 的变体：

java复制Page<User> page = new Page<>(1, 10);
IPage<User> userPage = userMapper.selectUserPage(page, param1, param2);

对应的 XML 映射文件：

xml复制<select id="selectUserPage" resultType="User">
    SELECT * FROM user WHERE department = #{param1} AND status = #{param2}
</select>

注意：使用自定义 SQL 时，MyBatis Plus 仍然会自动处理分页逻辑，你不需要在 SQL 中手动添加 LIMIT 子句。

2.3.3 不分页但获取总数

有时候你可能只需要获取记录总数而不需要分页数据：

java复制Page<User> page = new Page<>(1, 10, false); // 第三个参数设置为false表示不查询数据
userMapper.selectPage(page, wrapper);
long total = page.getTotal();

3. 高级应用与性能优化

3.1 多数据源环境下的分页配置

在使用动态数据源的情况下，你需要确保每个数据源都有正确的分页配置。以下是常见的配置方式：

java复制@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    
    // 主数据源分页配置
    PaginationInnerInterceptor primaryPagination = new PaginationInnerInterceptor(DbType.MYSQL);
    primaryPagination.setOptimizeJoin(true);
    
    // 从数据源分页配置
    PaginationInnerInterceptor secondaryPagination = new PaginationInnerInterceptor(DbType.POSTGRE_SQL);
    secondaryPagination.setMaxLimit(1000L);
    
    // 动态数据源会自动选择合适的拦截器
    interceptor.addInnerInterceptor(new DynamicDataSourceInnerInterceptor());
    interceptor.addInnerInterceptor(primaryPagination);
    interceptor.addInnerInterceptor(secondaryPagination);
    
    return interceptor;
}

3.2 深度分页性能问题解决方案

当处理大数据量时，传统的 LIMIT offset, size 分页方式在 offset 很大时性能会急剧下降。针对这个问题，有几种优化方案：

3.2.1 游标分页（基于ID）

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.gt("id", lastId) // 使用上一页最后一条记录的ID
      .orderByAsc("id")
      .last("LIMIT " + pageSize);
List<User> users = userMapper.selectList(wrapper);

3.2.2 子查询优化

sql复制SELECT * FROM user WHERE id >= (SELECT id FROM user ORDER BY id LIMIT #{offset}, 1) LIMIT #{size}

3.2.3 使用覆盖索引

确保你的查询能够使用覆盖索引，避免回表操作：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.select("id", "name") // 只查询索引包含的字段
      .eq("status", 1)
      .orderByAsc("create_time");

3.3 分页缓存策略

对于变化不频繁的数据，可以考虑实现分页缓存来提升性能：

java复制@Cacheable(value = "userPage", key = "#current + '-' + #size + '-' + #name")
public IPage<User> getUsersByPage(int current, int size, String name) {
    Page<User> page = new Page<>(current, size);
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.like(StringUtils.isNotBlank(name), "name", name);
    return userMapper.selectPage(page, wrapper);
}

4. 常见问题排查与解决方案

4.1 分页不生效的全面排查清单

当分页功能不工作时，可以按照以下步骤进行排查：

检查拦截器配置
- 确认配置类被 Spring 扫描到
- 检查是否使用了正确版本的配置方式
- 确认没有同时配置新旧两种拦截器
检查 SQL 执行情况
- 开启 MyBatis SQL 日志，查看实际执行的 SQL
- 确认是否生成了 COUNT 查询
- 检查 LIMIT 子句是否被正确添加
检查返回结果处理
- 确保没有在 Controller 中重新封装了返回结果
- 确认前端正确解析了返回的 IPage 结构
特殊场景检查
- 多数据源环境下是否每个数据源都配置了分页插件
- 自定义 SQL 是否干扰了分页逻辑
- 是否使用了某些特殊的 MyBatis 插件导致冲突

4.2 特定数据库的兼容性问题

不同的数据库在分页语法上有所差异。MyBatis Plus 虽然提供了多种数据库的支持，但在某些特殊情况下仍可能需要额外配置：

4.2.1 Oracle 数据库

Oracle 的分页语法较为特殊，需要使用 ROWNUM。如果你遇到 Oracle 分页问题，可以尝试以下配置：

java复制PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor(DbType.ORACLE);
paginationInterceptor.setOptimizeJoin(true);

4.2.2 SQL Server 2012 及以上版本

SQL Server 2012 开始支持 OFFSET-FETCH 语法，配置方式：

java复制PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor(DbType.SQL_SERVER);

4.3 与其它插件的冲突解决

MyBatis Plus 的分页插件可能会与某些 MyBatis 插件产生冲突，特别是那些也修改 SQL 的插件。常见的冲突场景包括：

多租户插件冲突
- 解决方案：调整插件执行顺序，确保分页插件在租户插件之后执行
SQL 性能分析插件冲突
- 解决方案：检查插件是否修改了 SQL 结构
自定义拦截器冲突
- 解决方案：检查拦截器的 @Intercepts 注解是否与分页插件重叠

可以通过调整拦截器的添加顺序来解决大部分冲突问题：

java复制@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    
    // 先添加其他拦截器
    interceptor.addInnerInterceptor(new TenantLineInnerInterceptor());
    
    // 最后添加分页拦截器
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
    
    return interceptor;
}

5. 实战经验与最佳实践

5.1 分页参数的安全处理

在实际项目中，我们需要对前端传入的分页参数进行校验和处理，以避免潜在的安全问题和性能问题：

java复制public Page<T> buildPage(Integer current, Integer size) {
    // 处理当前页
    int pageNum = (current == null || current < 1) ? 1 : current;
    
    // 处理每页大小
    int pageSize = (size == null || size < 1) ? 10 : size;
    pageSize = Math.min(pageSize, 100); // 限制最大每页数量
    
    return new Page<>(pageNum, pageSize);
}

5.2 统一分页响应格式

为了保持 API 的一致性，可以定义一个统一的分页响应格式：

java复制public class PageResult<T> {
    private long current;
    private long size;
    private long total;
    private long pages;
    private List<T> records;
    
    public static <T> PageResult<T> success(IPage<T> page) {
        PageResult<T> result = new PageResult<>();
        result.setCurrent(page.getCurrent());
        result.setSize(page.getSize());
        result.setTotal(page.getTotal());
        result.setPages(page.getPages());
        result.setRecords(page.getRecords());
        return result;
    }
    
    // getters and setters
}

在 Controller 中使用：

java复制@GetMapping("/users")
public PageResult<User> getUsers(@RequestParam(defaultValue = "1") int current,
                               @RequestParam(defaultValue = "10") int size) {
    Page<User> page = new Page<>(current, size);
    IPage<User> userPage = userMapper.selectPage(page, null);
    return PageResult.success(userPage);
}

5.3 前端分页组件集成建议

不同的前端框架对分页数据的处理方式有所不同，这里提供几个常见框架的集成建议：

5.3.1 Vue + Element UI

javascript复制// 表格数据获取
async fetchData() {
    const res = await axios.get('/api/users', {
        params: {
            current: this.currentPage,
            size: this.pageSize
        }
    });
    this.tableData = res.data.records;
    this.total = res.data.total;
}

// 分页组件
<el-pagination
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
    :current-page="currentPage"
    :page-sizes="[10, 20, 50, 100]"
    :page-size="pageSize"
    layout="total, sizes, prev, pager, next, jumper"
    :total="total">
</el-pagination>

5.3.2 React + Ant Design

jsx复制// 表格数据获取
const fetchData = async (pagination) => {
    const res = await axios.get('/api/users', {
        params: {
            current: pagination.current,
            size: pagination.pageSize
        }
    });
    setData(res.data.records);
    setPagination({
        ...pagination,
        total: res.data.total
    });
};

// 分页组件
<Table
    columns={columns}
    dataSource={data}
    pagination={pagination}
    onChange={handleTableChange}
/>

5.4 性能监控与调优

对于高频使用的分页接口，建议实施性能监控：

慢查询监控
- 设置分页查询的慢查询阈值
- 监控 COUNT 查询的执行时间
缓存命中率监控
- 对于缓存的分页结果，监控缓存命中率
- 根据命中率调整缓存策略
分页深度告警
- 监控用户访问的页码深度
- 对于频繁的深度分页访问进行告警

实现示例：

java复制@Aspect
@Component
@Slf4j
public class PagePerformanceAspect {
    
    @Around("execution(* com..mapper.*.selectPage(..))")
    public Object monitorPagePerformance(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        Object result = joinPoint.proceed();
        long costTime = System.currentTimeMillis() - startTime;
        
        if (result instanceof IPage) {
            IPage<?> page = (IPage<?>) result;
            log.info("分页查询执行时间: {}ms, 页码: {}, 每页大小: {}, 总记录数: {}",
                    costTime, page.getCurrent(), page.getSize(), page.getTotal());
            
            if (costTime > 1000) {
                log.warn("慢分页查询警告: 执行时间超过1秒");
            }
            
            if (page.getCurrent() > 100) {
                log.warn("深度分页警告: 用户访问了第{}页", page.getCurrent());
            }
        }
        
        return result;
    }
}

6. 扩展功能与进阶用法

6.1 自定义分页逻辑

在某些特殊场景下，你可能需要完全自定义分页逻辑。MyBatis Plus 提供了相应的扩展点：

java复制public class CustomPaginationInterceptor extends PaginationInnerInterceptor {
    @Override
    public void beforeQuery(Executor executor, MappedStatement ms, Object parameter, 
                          RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
        // 自定义分页前逻辑
    }
    
    @Override
    public void afterQuery(Executor executor, MappedStatement ms, Object parameter, 
                         RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql, 
                         IPage<?> page) {
        // 自定义分页后逻辑
    }
}

6.2 多表联查分页优化

对于多表联查的分页场景，常规的 COUNT 查询性能往往较差。可以通过以下方式优化：

使用冗余字段：在主表中冗余关联表的关键信息，避免联表查询
使用视图：创建预定义的视图简化复杂查询
使用子查询：优化 COUNT 查询的执行计划

示例：

java复制QueryWrapper<Order> wrapper = new QueryWrapper<>();
wrapper.select("o.*", "u.username as user_name")
      .from("order o")
      .leftJoin("user u on o.user_id = u.id")
      .eq("o.status", 1)
      .orderByDesc("o.create_time");

Page<Order> page = new Page<>(1, 10);
orderMapper.selectPage(page, wrapper);

6.3 流式分页处理

对于需要处理大量数据的导出场景，可以使用流式分页处理：

java复制public void exportLargeData(OutputStream outputStream) {
    int current = 1;
    int size = 1000;
    boolean hasNext = true;
    
    while (hasNext) {
        Page<User> page = new Page<>(current, size);
        IPage<User> userPage = userMapper.selectPage(page, null);
        
        processBatch(userPage.getRecords(), outputStream);
        
        hasNext = userPage.getCurrent() < userPage.getPages();
        current++;
    }
}

7. 版本升级与迁移指南

7.1 从旧版迁移到新版

如果你正在从 MyBatis Plus 3.4.0 之前的版本升级，需要注意以下变化：

拦截器配置变化
- 移除旧的 PaginationInterceptor 配置
- 添加新的 MybatisPlusInterceptor 配置
API 兼容性
- 大部分分页 API 保持兼容
- 某些过时方法已被标记为 @Deprecated
行为差异
- 新版对某些边界条件的处理更加严格
- 分页性能有所优化

7.2 跨大版本升级注意事项

当进行跨大版本升级（如 2.x → 3.x）时，除了分页插件的变化外，还需要注意：

依赖变化
- 检查 starter 依赖的坐标变化
- 确认 MyBatis 核心版本兼容性
配置迁移
- 重新审视所有自定义配置
- 测试关键功能是否正常
API 变化
- 检查项目中使用的 API 是否在新版中仍然可用
- 更新已废弃的 API 调用

8. 测试策略与质量保障

8.1 分页功能的单元测试

确保为分页功能编写全面的单元测试：

java复制@SpringBootTest
public class UserMapperPageTest {
    
    @Autowired
    private UserMapper userMapper;
    
    @Test
    public void testBasicPagination() {
        Page<User> page = new Page<>(1, 10);
        IPage<User> result = userMapper.selectPage(page, null);
        
        assertEquals(10, result.getRecords().size());
        assertTrue(result.getTotal() > 0);
    }
    
    @Test
    public void testPaginationWithCondition() {
        Page<User> page = new Page<>(1, 5);
        QueryWrapper<User> wrapper = new QueryWrapper<>();
        wrapper.like("name", "张");
        
        IPage<User> result = userMapper.selectPage(page, wrapper);
        
        assertTrue(result.getRecords().size() <= 5);
        result.getRecords().forEach(user -> 
            assertTrue(user.getName().contains("张")));
    }
}

8.2 性能测试要点

针对分页接口的性能测试应关注以下指标：

基础性能
- 不同页码的响应时间
- 不同页大小的响应时间
边界情况
- 第一页和最后一页的性能差异
- 超大页码的处理能力
并发性能
- 多用户并发访问时的稳定性
- 数据库连接池的使用情况

8.3 自动化测试集成

将分页测试集成到持续集成流程中：

yaml复制# Jenkinsfile 示例
pipeline {
    agent any
    
    stages {
        stage('Test') {
            steps {
                sh 'mvn test -Dtest=*PageTest'
            }
        }
    }
    
    post {
        always {
            junit '**/target/surefire-reports/*.xml'
        }
    }
}

9. 常见业务场景解决方案

9.1 带条件的分页查询

实际业务中经常需要根据多种条件进行分页查询：

java复制@GetMapping("/search")
public PageResult<User> searchUsers(
        @RequestParam(defaultValue = "1") int current,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer age,
        @RequestParam(required = false) Integer status) {
    
    Page<User> page = new Page<>(current, size);
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    
    wrapper.like(StringUtils.isNotBlank(name), "name", name)
          .eq(age != null, "age", age)
          .eq(status != null, "status", status)
          .orderByDesc("create_time");
    
    IPage<User> userPage = userMapper.selectPage(page, wrapper);
    return PageResult.success(userPage);
}

9.2 分页与排序结合

MyBatis Plus 支持灵活的多字段排序：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.orderBy(true, true, "age")  // 是否升序，是否优先，字段名
      .orderBy(true, false, "create_time");

9.3 分组分页查询

对于需要先分组再分页的场景，可以采用子查询方式：

java复制@Select("SELECT t.* FROM (SELECT department, COUNT(*) as count FROM user GROUP BY department) t LIMIT #{offset}, #{size}")
List<Map<String, Object>> selectGroupByDepartment(@Param("offset") long offset, @Param("size") long size);

@Select("SELECT COUNT(*) FROM (SELECT department FROM user GROUP BY department) t")
long countGroupByDepartment();

10. 生态系统集成

10.1 与 Spring Data 的兼容性

MyBatis Plus 的分页接口可以与 Spring Data 的 Pageable 兼容：

java复制public Page<User> findByCondition(Pageable pageable, String name) {
    Page<User> page = new Page<>(pageable.getPageNumber(), pageable.getPageSize());
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.like("name", name);
    return userMapper.selectPage(page, wrapper);
}

10.2 与 GraphQL 的集成

在 GraphQL 服务中实现分页查询：

java复制@GraphQLQuery(name = "users")
public IPage<User> getUsers(
        @GraphQLArgument(name = "page") int page,
        @GraphQLArgument(name = "size") int size) {
    return userMapper.selectPage(new Page<>(page, size), null);
}

对应的 GraphQL 查询：

graphql复制query {
  users(page: 1, size: 10) {
    records {
      id
      name
    }
    total
    pages
  }
}

10.3 与微服务的兼容设计

在微服务架构中，分页接口的设计需要考虑以下因素：

API 一致性：所有服务的分页接口保持相同结构和行为
性能考量：避免服务间的大数据量传输
错误处理：统一的分页参数验证和错误响应

示例微服务分页接口：

java复制@GetMapping("/api/users")
public ResponseEntity<PageResult<User>> getUsers(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String name) {
    
    if (page < 1 || size < 1 || size > 100) {
        return ResponseEntity.badRequest().build();
    }
    
    Page<User> mybatisPage = new Page<>(page, size);
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.like(StringUtils.isNotBlank(name), "name", name);
    
    IPage<User> result = userMapper.selectPage(mybatisPage, wrapper);
    return ResponseEntity.ok(PageResult.success(result));
}

11. 安全考量与防护措施

11.1 分页参数的安全校验

必须对前端传入的分页参数进行严格校验：

java复制public void validatePageParams(int page, int size) {
    if (page < 1) {
        throw new IllegalArgumentException("页码不能小于1");
    }
    if (size < 1 || size > 100) {
        throw new IllegalArgumentException("每页大小必须在1-100之间");
    }
}

11.2 SQL 注入防护

虽然 MyBatis Plus 的 QueryWrapper 已经提供了 SQL 注入防护，但在使用自定义 SQL 时仍需注意：

java复制// 不安全的写法
@Select("SELECT * FROM user WHERE name = '${name}' LIMIT #{offset}, #{size}")
List<User> findByNameUnsafe(@Param("name") String name, @Param("offset") int offset, @Param("size") int size);

// 安全的写法
@Select("SELECT * FROM user WHERE name = #{name} LIMIT #{offset}, #{size}")
List<User> findByNameSafe(@Param("name") String name, @Param("offset") int offset, @Param("size") int size);

11.3 防恶意爬取策略

对于公开的分页接口，需要防止恶意爬取全部数据：

速率限制：限制单个IP的请求频率
深度限制：拒绝超过最大页码的请求
验证码：对高频访问进行验证码验证