Mybatis分頁插件Mybatis-PageHelper

一、引入jar包

在 pom.xml 中添加如下依賴：

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper</artifactId>
    <version>5.1.6</version>
</dependency>

二、與spring 集成

在 Spring 配置文件中配置攔截器插件
環境：項目使用Spring4.1.2.RELEASE + SpringMVC4.1.2.RELEASE + Mybatis3.3.0

<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="mapperLocations">
        <array>
             <!-- mapper的xml文件地址 -->
            <value>classpath:mapper/*.xml</value>
        </array>
    </property>
        <!-- model 所的包 -->
    <property name="typeAliasesPackage" value="com.isea533.mybatis.model"/>
       <!-- 開始集成分頁插件 -->
    <property name="plugins">
        <array>
            <bean class="com.github.pagehelper.PageInterceptor">
                <!-- 這裏的幾個配置參數主要演示如何使用，如果不理解，一定要去掉下面的配置 ，詳細配置，詳見下面詳解-->
                <property name="properties">
                    <value>
                        helperDialect=mysql
                         supportMethodsArguments=true
                      </value>
                </property>
            </bean>
        </array>
    </property>
</bean>

三、頁插件參數介紹

分頁插件提供了多個可選參數，這些參數使用時，按照上面兩種配置方式中的示例配置即可。
分頁插件可選參數如下：
dialect：默認情況下會使用 PageHelper 方式進行分頁，如果想要實現自己的分頁邏輯，可以實現 Dialect(com.github.pagehelper.Dialect) 接口，然後配置該屬性爲實現類的全限定名稱。
下面幾個參數都是針對默認 dialect 情況下的參數。使用自定義 dialect 實現時，下面的參數沒有任何作用。

helperDialect：分頁插件會自動檢測當前的數據庫鏈接，自動選擇合適的分頁方式。 你可以配置helperDialect屬性來指定分頁插件使用哪種方言。配置時，可以使用下面的縮寫值：
oracle,mysql,mariadb,sqlite,hsqldb,postgresql,db2,sqlserver,informix,h2,sqlserver2012,derby
特別注意：使用 SqlServer2012 數據庫時，需要手動指定爲 sqlserver2012，否則會使用 SqlServer2005 的方式進行分頁。
你也可以實現 AbstractHelperDialect，然後配置該屬性爲實現類的全限定名稱即可使用自定義的實現方法。

offsetAsPageNum：默認值爲 false，該參數對使用 RowBounds 作爲分頁參數時有效。 當該參數設置爲 true 時，會將 RowBounds 中的 offset 參數當成 pageNum 使用，可以用頁碼和頁面大小兩個參數進行分頁。

rowBoundsWithCount：默認值爲false，該參數對使用 RowBounds 作爲分頁參數時有效。 當該參數設置爲true時，使用 RowBounds 分頁會進行 count 查詢。

pageSizeZero：默認值爲 false，當該參數設置爲 true 時，如果 pageSize=0 或者 RowBounds.limit = 0 就會查詢出全部的結果（相當於沒有執行分頁查詢，但是返回結果仍然是 Page 類型）。

reasonable：分頁合理化參數，默認值爲false。當該參數設置爲 true 時，pageNum<=0 時會查詢第一頁， pageNum>pages（超過總數時），會查詢最後一頁。默認false 時，直接根據參數進行查詢。

params：爲了支持startPage(Object params)方法，增加了該參數來配置參數映射，用於從對象中根據屬性名取值， 可以配置 pageNum,pageSize,count,pageSizeZero,reasonable，不配置映射的用默認值， 默認值爲pageNum=pageNum;pageSize=pageSize;count=countSql;reasonable=reasonable;pageSizeZero=pageSizeZero。

supportMethodsArguments：支持通過 Mapper 接口參數來傳遞分頁參數，默認值false，分頁插件會從查詢方法的參數值中，自動根據上面 params 配置的字段中取值，查找到合適的值時就會自動分頁。 使用方法可以參考測試代碼中的 com.github.pagehelper.test.basic 包下的 ArgumentsMapTest 和 ArgumentsObjTest。

autoRuntimeDialect：默認值爲 false。設置爲 true 時，允許在運行時根據多數據源自動識別對應方言的分頁 （不支持自動選擇sqlserver2012，只能使用sqlserver），用法和注意事項參考下面的場景五。

closeConn：默認值爲 true。當使用運行時動態數據源或沒有設置 helperDialect 屬性自動獲取數據庫類型時，會自動獲取一個數據庫連接， 通過該屬性來設置是否關閉獲取的這個連接，默認true關閉，設置爲 false 後，不會關閉獲取的連接，這個參數的設置要根據自己選擇的數據源來決定。

aggregateFunctions(5.1.5+)：默認爲所有常見數據庫的聚合函數，允許手動添加聚合函數（影響行數），所有以聚合函數開頭的函數，在進行 count 轉換時，會套一層。其他函數和列會被替換爲 count(0)，其中count列可以自己配置。

重要提示：
當 offsetAsPageNum=false 的時候，由於 PageNum 問題，RowBounds查詢的時候 reasonable 會強制爲 false。使用 PageHelper.startPage 方法不受影響。

四、使用場景

場景一
如果你仍然在用類似ibatis式的命名空間調用方式，你也許會用到rowBoundsWithCount， 分頁插件對RowBounds支持和 MyBatis 默認的方式是一致，默認情況下不會進行 count 查詢，如果你想在分頁查詢時進行 count 查詢， 以及使用更強大的 PageInfo 類，你需要設置該參數爲 true。

注： PageRowBounds 想要查詢總數也需要配置該屬性爲 true。

場景二
如果你仍然在用類似ibatis式的命名空間調用方式，你覺得 RowBounds 中的兩個參數 offset,limit 不如 pageNum,pageSize 容易理解， 你可以使用 offsetAsPageNum 參數，將該參數設置爲 true 後，offset會當成 pageNum 使用，limit 和 pageSize 含義相同。

場景三
如果覺得某個地方使用分頁後，你仍然想通過控制參數查詢全部的結果，你可以配置 pageSizeZero 爲 true， 配置後，當 pageSize=0 或者 RowBounds.limit = 0 就會查詢出全部的結果。

場景四
如果你分頁插件使用於類似分頁查看列表式的數據，如新聞列表，軟件列表， 你希望用戶輸入的頁數不在合法範圍（第一頁到最後一頁之外）時能夠正確的響應到正確的結果頁面， 那麼你可以配置 reasonable 爲 true，這時如果 pageNum<=0 會查詢第一頁，如果 pageNum>總頁數 會查詢最後一頁。

場景五

如果你在 Spring 中配置了動態數據源，並且連接不同類型的數據庫，這時你可以配置 autoRuntimeDialect 爲 true，這樣在使用不同數據源時，會使用匹配的分頁進行查詢。 這種情況下，你還需要特別注意 closeConn 參數，由於獲取數據源類型會獲取一個數據庫連接，所以需要通過這個參數來控制獲取連接後，是否關閉該連接。 默認爲 true，有些數據庫連接關閉後就沒法進行後續的數據庫操作。而有些數據庫連接不關閉就會很快由於連接數用完而導致數據庫無響應。所以在使用該功能時，特別需要注意你使用的數據源是否需要關閉數據庫連接。

當不使用動態數據源而只是自動獲取 helperDialect 時，數據庫連接只會獲取一次，所以不需要擔心佔用的這一個連接是否會導致數據庫出錯，但是最好也根據數據源的特性選擇是否關閉連接。

五、代碼使用demo

分頁插件支持以下幾種調用方式：

**//第一種，RowBounds方式的調用**
List<Country> list = sqlSession.selectList("x.y.selectIf", null, new RowBounds(0, 10));

**//第二種，Mapper接口方式的調用，推薦這種使用方式。**
PageHelper.startPage(1, 10);
List<Country> list = countryMapper.selectIf(1);

**//第三種，Mapper接口方式的調用，推薦這種使用方式。**
PageHelper.offsetPage(1, 10);
List<Country> list = countryMapper.selectIf(1);

**//第四種，參數方法調用**
//存在以下 Mapper 接口方法，你不需要在 xml 處理後兩個參數
//配置文件中需要增加配置參數
public interface CountryMapper {
    List<Country> selectByPageNumSize(
            @Param("user") User user,
            @Param("pageNum") int pageNum, 
            @Param("pageSize") int pageSize);
}
//配置supportMethodsArguments=true
//在代碼中直接調用：
List<Country> list = countryMapper.selectByPageNumSize(user, 1, 10);

**//第五種，參數對象**
//如果 pageNum 和 pageSize 存在於 User 對象中，只要參數有值，也會被分頁
//有如下 User 對象
public class User {
    //其他fields
    //下面兩個參數名和 params 配置的名字一致
    private Integer pageNum;
    private Integer pageSize;
}
//存在以下 Mapper 接口方法，你不需要在 xml 處理後兩個參數
public interface CountryMapper {
    List<Country> selectByPageNumSize(User user);
}
//當 user 中的 pageNum!= null && pageSize!= null 時，會自動分頁
List<Country> list = countryMapper.selectByPageNumSize(user);

**//第六種，ISelect 接口方式**
//jdk6,7用法，創建接口
Page<Country> page = PageHelper.startPage(1, 10).doSelectPage(new ISelect() {
    @Override
    public void doSelect() {
        countryMapper.selectGroupBy();
    }
});
//jdk8 lambda用法
//通過當前線程存儲分頁數據實現
Page<Country> page = PageHelper.startPage(1, 10).doSelectPage(()-> countryMapper.selectGroupBy());

//也可以直接返回PageInfo，注意doSelectPageInfo方法和doSelectPage
pageInfo = PageHelper.startPage(1, 10).doSelectPageInfo(new ISelect() {
    @Override
    public void doSelect() {
        countryMapper.selectGroupBy();
    }
});

//對應的lambda用法
//通過當前線程存儲分頁數據實現
pageInfo = PageHelper.startPage(1, 10).doSelectPageInfo(() -> countryMapper.selectGroupBy());

//count查詢，返回一個查詢語句的count數
//通過當前線程存儲分頁數據實現
long total = PageHelper.count(new ISelect() {
    @Override
    public void doSelect() {
        countryMapper.selectLike(country);
    }
});
//lambda
total = PageHelper.count(()->countryMapper.selectLike(country));

七、集成中遇到的問題

問題：按照官方文檔對接做了相應的配置和引入了相應的jar ，但是無法實現分頁，debug也無法進入PageInterceptor攔截器中的相應轉換sql的方法
問題分析：
A、最初懷疑是配置問題，覈對了配置和官方配置無差異
B、還以是插件與spring版本不兼容，換了插件的版本依然無法分頁
C、debug PageInterceptor攔截器，無法進入相應的sql轉換方法
解決方案：通過公司高手debug 相應的 SqlSessionFactory 類，才發現，我配置了多個 SqlSessionFactory ，並且我sql的mapper方法，沒有走到，配置PageInterceptor攔截器的SqlSessionFactory，導致無法分頁。 最終將項目中的多個SqlSessionFactory 合併爲一個帶有 PageInterceptor攔截器的 SqlSessionFactory問題得以解決。

版權聲明：部分內容引用原插件開發作者，github地址：https://github.com/pagehelper/Mybatis-PageHelper/blob/master/wikis/zh/HowToUse.md