PageHelper 插件原理

ps：如果这篇帖子对于还在找工作和找实习的你有所帮助，可以关注我，给本贴点赞、评论、收藏并订阅专栏；同时不要吝啬您的花花

PageHelper是MyBatis生态中最常用的无侵入式分页插件，核心价值是无需手动编写分页SQL，只需一行代码即可实现分页查询，彻底规避手写分页的语法差异、参数错乱等问题。其底层原理高度依赖MyBatis原生扩展机制，整体可概括为：ThreadLocal线程隔离存储分页参数 + MyBatis拦截器拦截查询流程 + 动态适配数据库改写分页SQL，全程无侵入业务代码和原生Mapper SQL。

一、核心底层：三大基石原理

1. ThreadLocal：分页参数的线程隔离容器

分页参数（页码pageNum、每页条数pageSize、是否查询总数count、排序规则等）需要保证线程独享，避免多线程并发请求下参数互相污染。PageHelper采用ThreadLocal实现参数存储，核心逻辑如下：

存储时机：调用PageHelper.startPage(pageNum, pageSize)方法时，插件会将分页参数封装为Page对象，存入当前线程的ThreadLocal副本中，仅当前线程可见。
清理机制：分页查询执行完毕后，插件会自动清空ThreadLocal中的分页参数，防止线程复用（如线程池）导致的分页参数残留，避免后续非分页查询被误拦截。
核心作用：实现分页参数与查询线程的绑定，让拦截器能精准获取当前查询的分页规则，是实现无侵入分页的前提。

2. MyBatis拦截器：分页逻辑的核心入口

PageHelper本质是一个MyBatis插件，通过实现MyBatis的Interceptor接口，拦截MyBatis查询的核心执行链路，这是插件能改写SQL的关键。

拦截目标：主要拦截MyBatis执行器Executor的query方法（所有查询操作的统一入口），部分版本还会拦截StatementHandler的参数处理和SQL执行方法，确保拦截时机精准。
拦截逻辑：MyBatis执行查询前，会先经过PageHelper的拦截器；拦截器先从ThreadLocal中获取分页参数，判断当前查询是否需要分页，无参数则直接放行，有参数则进入SQL改写流程。
插件注册：通过MyBatis配置文件或Spring配置类注册插件，MyBatis启动时会加载拦截器，将其植入查询执行链路。

3. SQL动态改写：适配数据库的分页语法

拦截器确认需要分页后，会对原生业务SQL进行解析和改写，自动拼接对应数据库的分页语法，同时生成count统计SQL查询总记录数，核心分为两步：

count查询改写：基于原生SQL生成统计总条数的SQL（如SELECT COUNT(0) FROM (原生SQL) AS tmp_count），查询数据总条数，用于计算总页数、偏移量等分页元数据。
分页查询改写：根据当前连接的数据库类型，拼接专属分页语法，屏蔽不同数据库的分页差异，实现跨库分页兼容。

二、完整分页执行全流程

从调用分页方法到返回分页结果，PageHelper的执行链路环环相扣，全程无业务侵入，具体步骤如下：

开启分页：业务代码调用PageHelper.startPage(pageNum, pageSize)，插件将分页参数存入当前线程ThreadLocal，标记下一次查询为分页查询。
执行Mapper查询：调用MyBatis的Mapper接口方法，触发原生SQL查询，进入MyBatis执行器流程。
拦截器拦截：PageHelper拦截器捕获Executor.query方法，从ThreadLocal中提取分页参数，校验参数合法性（如页码合法性、分页合理化）。
执行count统计：拦截器生成count SQL并执行，获取数据总记录数，计算分页偏移量（offset = (pageNum-1)*pageSize）。
改写分页SQL：根据数据库类型，在原生SQL末尾追加分页语法，生成最终分页SQL。
执行分页查询：MyBatis执行改写后的分页SQL，获取当前页数据列表。
封装分页结果：将当前页数据、总记录数、总页数、页码、每页条数等元数据封装为Page/PageInfo对象返回。
清理线程参数：查询完毕后，自动清空ThreadLocal中的分页参数，避免线程污染。

三、多数据库分页语法适配原理

PageHelper内置主流数据库的分页语法解析规则，通过数据库方言自动识别，动态生成对应分页SQL，常见适配如下：

MySQL、MariaDB	LIMIT offset, pageSize	原生SQL末尾直接拼接LIMIT子句
Oracle	ROWNUM分页	嵌套SQL+ROWNUM筛选，实现偏移和条数限制
SQL Server	OFFSET ... FETCH NEXT	拼接OFFSET分页子句，适配2012及以上版本
PostgreSQL	LIMIT pageSize OFFSET offset	末尾拼接LIMIT+OFFSET子句

插件支持自定义方言，可通过配置扩展小众数据库的分页语法，满足特殊业务场景需求。

四、核心源码简化解析

PageHelper的核心逻辑集中在PageInterceptor（拦截器核心类）和Page（分页参数封装类），关键代码逻辑简化如下：

// 1. 分页参数存储（PageHelper.startPage）
public static <E> Page<E> startPage(int pageNum, int pageSize) {
    // 封装分页参数
    Page<E> page = new Page<>(pageNum, pageSize);
    // 存入ThreadLocal
    LOCAL_PAGE.set(page);
    return page;
}

// 2. 拦截器核心拦截方法（PageInterceptor.intercept）
@Override
public Object intercept(Invocation invocation) throws Throwable {
    // 从ThreadLocal获取分页参数
    Page<?> page = LOCAL_PAGE.get();
    if (page == null) {
        // 无分页参数，直接放行
        return invocation.proceed();
    }
    try {
        // 执行count查询
        long total = executeCount(invocation);
        page.setTotal(total);
        // 改写分页SQL并执行
        return executePageQuery(invocation, page);
    } finally {
        // 清空ThreadLocal，防止线程污染
        LOCAL_PAGE.remove();
    }
}

源码中还包含SQL解析、方言匹配、参数校验、分页合理化（如页码小于1时自动修正为1）等逻辑，进一步提升插件的稳定性和易用性。