快捷導航

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

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

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

1. 問題現(xiàn)象

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

錯誤代碼示例

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

2. 原理分析

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

2.1 執(zhí)行流程

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

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

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

SQL 改寫：

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

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

2.2 失效原因

在上述錯誤代碼中：

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

3. 正確實現(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í)行查詢（攔截器生效，自動改寫 SQL 并執(zhí)行 Count 查詢）
    // 注意：此時返回的 list 實際類型為 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ù)
         response.setResult(wrapPageResult(pageInfo));
    } else {
         response.setResult(Collections.EMPTY_LIST);
    }
    
    return response;
}