PageHelper中分頁失效的原因分析與正確方法實(shí)踐

更新時(shí)間：2025年11月20日 09:06:59 作者：秧歌star519

在使用 PageHelper 插件開發(fā)查詢接口時(shí),有時(shí)會(huì)出現(xiàn)分頁失效的情況,下面小編就和大家詳細(xì)講講分頁失效的原因分析與正確方法,希望對(duì)大家有所幫助

1. 問題現(xiàn)象

在使用 PageHelper 插件開發(fā)查詢接口時(shí)，出現(xiàn)分頁失效的情況：接口返回了全部數(shù)據(jù)而非當(dāng)前頁數(shù)據(jù)，且 PageInfo 對(duì)象中的分頁元數(shù)據(jù)（如 total 總條數(shù)、pages 總頁數(shù)）計(jì)算錯(cuò)誤。

錯(cuò)誤代碼示例

public BaseResponse<MyDataDTO> queryDataList(int pageNum, int pageSize, Map<String, Object> params) {
    BaseResponse response = new BaseResponse();
    
    // 1. 錯(cuò)誤：在設(shè)置分頁參數(shù)前執(zhí)行了數(shù)據(jù)庫查詢
    List<MyDataDTO> dataList = myMapper.selectData(params);
    
    // 2. 判空邏輯
    if (!CollectionUtils.isEmpty(dataList)) {
        // 3. 錯(cuò)誤：查詢?cè)缫淹瓿?，此時(shí)調(diào)用 startPage 無效
        PageHelper.startPage(pageNum, pageSize);
        
        // 4. 錯(cuò)誤：直接使用全量 List 包裝 PageInfo，無法獲取數(shù)據(jù)庫真實(shí)總數(shù)
        PageInfo<MyDataDTO> pageInfo = new PageInfo<>(dataList);
        
        response.setResult(wrapPageResult(pageInfo));
        return response;
    }
    
    response.setResult(Collections.EMPTY_LIST);
    return response;
}

2. 原理分析

PageHelper 的核心機(jī)制基于 ThreadLocal 和 MyBatis 攔截器（Interceptor）。

2.1 執(zhí)行流程

PageHelper 不是在內(nèi)存中對(duì)結(jié)果集進(jìn)行截取，而是通過攔截器修改 SQL 語句。

設(shè)置參數(shù)：調(diào)用 PageHelper.startPage(...) 時(shí)，插件會(huì)將分頁參數(shù)（pageNum, pageSize）存入當(dāng)前線程的 ThreadLocal 中。

攔截 SQL：當(dāng) MyBatis 執(zhí)行 Mapper 方法時(shí)，PageHelper 攔截器會(huì)觸發(fā)。

SQL 改寫：

攔截器檢查 ThreadLocal 中是否存在分頁參數(shù)。
若存在：攔截器會(huì)根據(jù)數(shù)據(jù)庫方言（如 MySQL）生成 SELECT COUNT(0) 語句獲取總數(shù)，并將原 SQL 改寫為帶 LIMIT/OFFSET 的分頁 SQL 執(zhí)行。
若不存在：攔截器直接放行，執(zhí)行原始 SQL。

清理上下文：SQL 執(zhí)行結(jié)束后，攔截器會(huì)清除 ThreadLocal 中的分頁參數(shù)，避免污染后續(xù)查詢。

2.2 失效原因

在上述錯(cuò)誤代碼中：

執(zhí)行順序錯(cuò)誤：myMapper.selectData 在 PageHelper.startPage 之前執(zhí)行。
攔截失敗：執(zhí)行查詢時(shí)，ThreadLocal 中沒有任何分頁參數(shù)，攔截器未生效，MyBatis 執(zhí)行了全量查詢。
參數(shù)無效：查詢結(jié)束后才調(diào)用 startPage，雖然設(shè)置了 ThreadLocal，但 SQL 交互已結(jié)束，該參數(shù)未被消費(fèi)。
元數(shù)據(jù)錯(cuò)誤：PageInfo 接收的是全量 List，因此它只能基于 List 的大小計(jì)算 total，導(dǎo)致分頁信息不符合預(yù)期。

3. 正確實(shí)現(xiàn)

核心原則：PageHelper.startPage 必須緊鄰 Mapper 查詢方法之前調(diào)用。

修正代碼

public BaseResponse<MyDataDTO> queryDataList(int pageNum, int pageSize, Map<String, Object> params) {
    BaseResponse response = new BaseResponse();

    // 1. 設(shè)置分頁參數(shù)（存入 ThreadLocal）
    PageHelper.startPage(pageNum, pageSize);
    
    // 2. 執(zhí)行查詢（攔截器生效，自動(dòng)改寫 SQL 并執(zhí)行 Count 查詢）
    // 注意：此時(shí)返回的 list 實(shí)際類型為 Page<E>
    List<MyDataDTO> dataList = myMapper.selectData(params);

    // 3. 獲取分頁結(jié)果
    PageInfo<MyDataDTO> pageInfo = new PageInfo<>(dataList);
    
    // 4. 結(jié)果處理（PageInfo 可安全處理空集合）
    if (!CollectionUtils.isEmpty(dataList)) {
         // pageInfo.getTotal() 為數(shù)據(jù)庫真實(shí)總數(shù)
         response.setResult(wrapPageResult(pageInfo));
    } else {
         response.setResult(Collections.EMPTY_LIST);
    }
    
    return response;
}