分页插件

引言

MyBatis-Plus 分页插件是基于 MyBatis 拦截器实现的物理分页组件，通过拦截 SQL 自动拼接分页语法与统计总记录数的 COUNT SQL，无需手动编写分页相关语句，支持多种数据库类型。 MyBatis-Plus 3.4.0 及以上版本推荐使用 MybatisPlusInterceptor 统一管理插件，替代旧版 PaginationInterceptor，插件扩展性与稳定性更强。

Spring Boot 配置

在 Spring Boot 项目中，通过 Java 配置类注册分页插件，这是官方推荐的集成方式。

import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@MapperScan("填写你的 Mapper 接口扫描包路径")
public class MybatisPlusConfig {

    /**
     * 注册 MyBatis-Plus 插件链，分页插件添加其中
     */
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 添加分页内部拦截器，指定数据库类型
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        // 多插件配置场景：分页插件必须添加在插件链的最后一位
        return interceptor;
    }
}

配置说明

DbType 选型 单一数据源建议指定具体数据库类型（如 DbType.MYSQL、DbType.ORACLE、DbType.POSTGRE_SQL），提升分页语法匹配效率；多数据源场景可不配置，插件会自动识别。
多插件规则 若同时配置防全表更新删除、动态表名等插件，分页插件必须最后添加，避免 COUNT SQL 解析异常。

PaginationInnerInterceptor

支持自定义配置，适配不同业务的分页规则：

属性名	类型	默认值	描述
overflow	boolean	false	分页溢出处理，true 时超出总页数自动跳转至第 1 页，false 时返回空数据
maxLimit	Long	无限制	单页最大数据条数限制，防止恶意请求查询全量数据
dbType	DbType	自动识别	数据库类型，手动配置可提升性能
dialect	IDialect	默认实现	分页方言实现类，可自定义扩展特殊数据库分页语法

自定义分页

分页插件不仅支持 MyBatis-Plus 自带 CRUD 分页，也支持自定义 Mapper 方法的物理分页，无需手动编写 limit 语法。

Mapper 接口定义

支持三种常用定义方式，插件会自动识别 IPage 类型参数并处理分页：

import com.baomidou.mybatisplus.core.metadata.IPage;
import org.apache.ibatis.annotations.Param;
import java.util.List;

public interface UserMapper {
    // 1. 返回 IPage，最常用方式
    IPage<UserVo> selectUserPage(IPage<?> page, @Param("state") Integer state);

    // 2. 返回 List，需手动封装分页结果
    List<UserVo> selectUserList(IPage<UserVo> page, @Param("state") Integer state);

    // 3. 自定义分页类（继承 IPage/Page）
    MyPage<UserVo> selectCustomPage(MyPage<UserVo> page, @Param("state") Integer state);
}

XML 映射文件

自定义 SQL 只需编写业务查询语句，插件自动拼接分页语法：

<select id="selectUserPage" resultType="com.example.vo.UserVo">
    SELECT id, name, create_time FROM user WHERE state = #{state}
</select>

分页参数取值

若需在 XML 中使用分页对象属性，通过 page.属性名 获取：

SELECT * FROM user WHERE state = #{state}
ORDER BY id DESC
LIMIT #{page.current}, #{page.size}

分页关闭方式

返回 IPage 时：page 参数不可为 null，传入 size < 0 可临时关闭分页，返回全量数据；
返回 List 时：page 参数可为 null，插件不执行分页逻辑。

使用示例

Service 层调用自带分页方法，快速实现分页查询：

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import org.springframework.stereotype.Service;

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Override
    public IPage<User> getUserPage(Integer current, Integer size) {
        // 初始化分页对象：第 current 页，每页 size 条
        IPage<User> page = new Page<>(current, size);
        // 执行分页查询
        return userMapper.selectPage(page, null);
    }
}

Page 与 IPage

Page 是 IPage 接口的默认实现类，封装了分页核心参数与结果数据，支持自定义扩展：

属性名	类型	默认值	描述
records	List<T>	emptyList	分页查询返回的数据列表
total	Long	0	符合条件的总记录数
size	Long	10	每页显示数据条数
current	Long	1	当前页码
orders	List<OrderItem>	emptyList	排序字段集合，支持多字段排序
optimizeCountSql	boolean	true	自动优化 COUNT SQL，提升统计性能
optimizeJoinOfCountSql	boolean	true	优化 COUNT SQL 时移除无意义的 LEFT JOIN
searchCount	boolean	true	是否查询总记录数，false 可提升查询速度
maxLimit	Long	无限制	单页数据条数上限，优先级高于拦截器属性
countId	String	空	自定义 COUNT 查询的 Statement ID，适配复杂统计 SQL

注意事项

COUNT SQL 优化 插件会自动优化 COUNT SQL，不参与 WHERE 条件的 LEFT JOIN 会被移除；涉及 LEFT JOIN 的查询，建议给表和字段添加别名，避免解析异常。
多插件执行顺序 分页插件必须放在 MybatisPlusInterceptor 插件链的最后，否则会导致 COUNT SQL 执行结果错误。
大数据量分页 大数据量场景可关闭 searchCount，不查询总记录数，提升查询效率。
排序规范 通过 Page 的 orders 属性设置排序，避免在 XML 中硬编码排序语法，便于维护。
自定义分页模型 需扩展分页属性时，可继承 Page 类或实现 IPage 接口，完成自定义分页对象封装。