手把手教你開發 MyBatis 分頁插件

作者：江南一點雨 2024-04-02 08:58:13

今天主要和小伙伴們分享了我們如何自己開發一個 MyBatis 插件，插件功能其實都是次要的，最主要是希望小伙伴們能夠理解 MyBatis 的工作流程。

在日常開發中，小伙伴們多多少少都有用過 MyBatis 插件，松哥猜測大家用的最多的就是 MyBatis 的分頁插件！不知道小伙伴們有沒有想過有一天自己也來開發一個 MyBatis 插件？

其實自己動手擼一個 MyBatis 插件并不難，今天松哥就把手帶大家擼一個 MyBatis 插件！

1.MyBatis 插件接口

即使你沒開發過 MyBatis 插件，估計也能猜出來，MyBatis 插件是通過攔截器來起作用的，MyBatis 框架在設計的時候，就已經為插件的開發預留了相關接口，如下：

public interface Interceptor {

  Object intercept(Invocation invocation) throws Throwable;

  default Object plugin(Object target) {
    return Plugin.wrap(target, this);
  }

  default void setProperties(Properties properties) {
    // NOP
  }

}

這個接口中就三個方法，第一個方法必須實現，后面兩個方法都是可選的。三個方法作用分別如下：

intercept：這個就是具體的攔截方法，我們自定義 MyBatis 插件時，一般都需要重寫該方法，我們插件所完成的工作也都是在該方法中完成的。
plugin：這個方法的參數 target 就是攔截器要攔截的對象，一般來說我們不需要重寫該方法。Plugin.wrap 方法會自動判斷攔截器的簽名和被攔截對象的接口是否匹配，如果匹配，才會通過動態代理攔截目標對象。
setProperties：這個方法用來傳遞插件的參數，可以通過參數來改變插件的行為。我們定義好插件之后，需要對插件進行配置，在配置的時候，可以給插件設置相關屬性，設置的屬性可以通過該方法獲取到。插件屬性設置像下面這樣：

<plugins>
    <plugin interceptor="org.javaboy.mybatis03.plugin.CamelInterceptor">
        <property name="xxx" value="xxx"/>
    </plugin>
</plugins>

2.MyBatis 攔截器簽名

攔截器定義好了后，攔截誰？

這個就需要攔截器簽名來完成了！

攔截器簽名是一個名為 @Intercepts 的注解，該注解中可以通過 @Signature 配置多個簽名。@Signature 注解中則包含三個屬性：

type: 攔截器需要攔截的接口，有 4 個可選項，分別是：Executor、ParameterHandler、ResultSetHandler 以及 StatementHandler。
method: 攔截器所攔截接口中的方法名，也就是前面四個接口中的方法名，接口和方法要對應上。
args: 攔截器所攔截方法的參數類型，通過方法名和參數類型可以鎖定唯一一個方法。

一個簡單的簽名可能像下面這樣：

@Intercepts(@Signature(
        type = ResultSetHandler.class,
        method = "handleResultSets",
        args = {Statement.class}
))
public class CamelInterceptor implements Interceptor {
    //...
}

3.被攔截的對象

根據前面的介紹，被攔截的對象主要有如下四個：

Executor

public interface Executor {

  ResultHandler NO_RESULT_HANDLER = null;

  int update(MappedStatement ms, Object parameter) throws SQLException;

  <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey cacheKey, BoundSql boundSql) throws SQLException;

  <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException;

  <E> Cursor<E> queryCursor(MappedStatement ms, Object parameter, RowBounds rowBounds) throws SQLException;

  List<BatchResult> flushStatements() throws SQLException;

  void commit(boolean required) throws SQLException;

  void rollback(boolean required) throws SQLException;

  CacheKey createCacheKey(MappedStatement ms, Object parameterObject, RowBounds rowBounds, BoundSql boundSql);

  boolean isCached(MappedStatement ms, CacheKey key);

  void clearLocalCache();

  void deferLoad(MappedStatement ms, MetaObject resultObject, String property, CacheKey key, Class<?> targetType);

  Transaction getTransaction();

  void close(boolean forceRollback);

  boolean isClosed();

  void setExecutorWrapper(Executor executor);

}

各方法含義分別如下：

update：該方法會在所有的 INSERT、 UPDATE、 DELETE 執行時被調用，如果想要攔截這些操作，可以通過該方法實現。
query：該方法會在 SELECT 查詢方法執行時被調用，方法參數攜帶了很多有用的信息，如果需要獲取，可以通過該方法實現。
queryCursor：當 SELECT 的返回類型是 Cursor 時，該方法會被調用。
flushStatements：當 SqlSession 方法調用 flushStatements 方法或執行的接口方法中帶有 @Flush 注解時該方法會被觸發。
commit：當 SqlSession 方法調用 commit 方法時該方法會被觸發。
rollback：當 SqlSession 方法調用 rollback 方法時該方法會被觸發。
getTransaction：當 SqlSession 方法獲取數據庫連接時該方法會被觸發。
close：該方法在懶加載獲取新的 Executor 后會被觸發。
isClosed：該方法在懶加載執行查詢前會被觸發。

ParameterHandler

public interface ParameterHandler {

  Object getParameterObject();

  void setParameters(PreparedStatement ps) throws SQLException;

}

各方法含義分別如下：

getParameterObject：在執行存儲過程處理出參的時候該方法會被觸發。
setParameters：設置 SQL 參數時該方法會被觸發。

ResultSetHandler

public interface ResultSetHandler {

  <E> List<E> handleResultSets(Statement stmt) throws SQLException;

  <E> Cursor<E> handleCursorResultSets(Statement stmt) throws SQLException;

  void handleOutputParameters(CallableStatement cs) throws SQLException;

}

各方法含義分別如下：

handleResultSets：該方法會在所有的查詢方法中被觸發（除去返回值類型為 Cursor的查詢方法），一般來說，如果我們想對查詢結果進行二次處理，可以通過攔截該方法實現。
handleCursorResultSets：當查詢方法的返回值類型為 Cursor時，該方法會被觸發。
handleOutputParameters：使用存儲過程處理出參的時候該方法會被調用。

StatementHandler

public interface StatementHandler {

  Statement prepare(Connection connection, Integer transactionTimeout)
      throws SQLException;

  void parameterize(Statement statement)
      throws SQLException;

  void batch(Statement statement)
      throws SQLException;

  int update(Statement statement)
      throws SQLException;

  <E> List<E> query(Statement statement, ResultHandler resultHandler)
      throws SQLException;

  <E> Cursor<E> queryCursor(Statement statement)
      throws SQLException;

  BoundSql getBoundSql();

  ParameterHandler getParameterHandler();

}

各方法含義分別如下：

prepare：該方法在數據庫執行前被觸發。
parameterize：該方法在 prepare 方法之后執行，用來處理參數信息。
batch：如果 MyBatis 的全劇配置中配置了 defaultExecutorType=”BATCH”，執行數據操作時該方法會被調用。
update：更新操作時該方法會被觸發。
query：該方法在 SELECT 方法執行時會被觸發。
queryCursor：該方法在 SELECT 方法執行時，并且返回值為 Cursor 時會被觸發。

在開發一個具體的插件時，我們應當根據自己的需求來決定到底攔截哪個方法。

4.開發分頁插件

4.1 內存分頁

MyBatis 中提供了一個不太好用的內存分頁功能，就是一次性把所有數據都查詢出來，然后在內存中進行分頁處理，這種分頁方式效率很低，基本上沒啥用，但是如果我們想要自定義分頁插件，就需要對這種分頁方式有一個簡單了解。

內存分頁的使用方式如下，首先在 Mapper 中添加 RowBounds 參數，如下：

public interface UserMapper {
    List<User> getAllUsersByPage(RowBounds rowBounds);
}

然后在 XML 文件中定義相關 SQL：

<select id="getAllUsersByPage" resultType="org.javaboy.mybatis03.model.User">
    select * from user
</select>

可以看到，在 SQL 定義時，壓根不用管分頁的事情，MyBatis 會查詢到所有的數據，然后在內存中進行分頁處理。

Mapper 中方法的調用方式如下：

@Test
public void test3() {
    UserMapper userMapper = sqlSessionFactory.openSession().getMapper(UserMapper.class);
    RowBounds rowBounds = new RowBounds(1,2);
    List<User> list = userMapper.getAllUsersByPage(rowBounds);
    for (User user : list) {
        System.out.println("user = " + user);
    }
}

構建 RowBounds 時傳入兩個參數，分別是 offset 和 limit，對應分頁 SQL 中的兩個參數。也可以通過 RowBounds.DEFAULT 的方式構建一個 RowBounds 實例，這種方式構建出來的 RowBounds 實例，offset 為 0，limit 則為 Integer.MAX_VALUE，也就相當于不分頁。

這就是 MyBatis 中提供的一個很不實用的內存分頁功能。

了解了 MyBatis 自帶的內存分頁之后，接下來我們就可以來看看如何自定義分頁插件了。

4.2 自定義分頁插件

首先要聲明一下，這里松哥帶大家自定義 MyBatis 分頁插件，主要是想通過這個東西讓小伙伴們了解自定義 MyBatis 插件的一些條條框框，了解整個自定義插件的流程，分頁插件并不是我們的目的，自定義分頁插件只是為了讓大家的學習過程變得有趣一些而已。

接下來我們就來開啟自定義分頁插件之旅。

首先我們需要自定義一個 RowBounds，因為 MyBatis 原生的 RowBounds 是內存分頁，并且沒有辦法獲取到總記錄數（一般分頁查詢的時候我們還需要獲取到總記錄數），所以我們自定義 PageRowBounds，對原生的 RowBounds 功能進行增強，如下：

public class PageRowBounds extends RowBounds {
    private Long total;

    public PageRowBounds(int offset, int limit) {
        super(offset, limit);
    }

    public PageRowBounds() {
    }

    public Long getTotal() {
        return total;
    }

    public void setTotal(Long total) {
        this.total = total;
    }
}

可以看到，我們自定義的 PageRowBounds 中增加了 total 字段，用來保存查詢的總記錄數。

接下來我們自定義攔截器 PageInterceptor，如下：

@Intercepts(@Signature(
        type = Executor.class,
        method = "query",
        args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}
))
public class PageInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        Object[] args = invocation.getArgs();
        MappedStatement ms = (MappedStatement) args[0];
        Object parameterObject = args[1];
        RowBounds rowBounds = (RowBounds) args[2];
        if (rowBounds != RowBounds.DEFAULT) {
            Executor executor = (Executor) invocation.getTarget();
            BoundSql boundSql = ms.getBoundSql(parameterObject);
            Field additionalParametersField = BoundSql.class.getDeclaredField("additionalParameters");
            additionalParametersField.setAccessible(true);
            Map<String, Object> additionalParameters = (Map<String, Object>) additionalParametersField.get(boundSql);
            if (rowBounds instanceof PageRowBounds) {
                MappedStatement countMs = newMappedStatement(ms, Long.class);
                CacheKey countKey = executor.createCacheKey(countMs, parameterObject, RowBounds.DEFAULT, boundSql);
                String countSql = "select count(*) from (" + boundSql.getSql() + ") temp";
                BoundSql countBoundSql = new BoundSql(ms.getConfiguration(), countSql, boundSql.getParameterMappings(), parameterObject);
                Set<String> keySet = additionalParameters.keySet();
                for (String key : keySet) {
                    countBoundSql.setAdditionalParameter(key, additionalParameters.get(key));
                }
                List<Object> countQueryResult = executor.query(countMs, parameterObject, RowBounds.DEFAULT, (ResultHandler) args[3], countKey, countBoundSql);
                Long count = (Long) countQueryResult.get(0);
                ((PageRowBounds) rowBounds).setTotal(count);
            }
            CacheKey pageKey = executor.createCacheKey(ms, parameterObject, rowBounds, boundSql);
            pageKey.update("RowBounds");
            String pageSql = boundSql.getSql() + " limit " + rowBounds.getOffset() + "," + rowBounds.getLimit();
            BoundSql pageBoundSql = new BoundSql(ms.getConfiguration(), pageSql, boundSql.getParameterMappings(), parameterObject);
            Set<String> keySet = additionalParameters.keySet();
            for (String key : keySet) {
                pageBoundSql.setAdditionalParameter(key, additionalParameters.get(key));
            }
            List list = executor.query(ms, parameterObject, RowBounds.DEFAULT, (ResultHandler) args[3], pageKey, pageBoundSql);
            return list;
        }
        //不需要分頁，直接返回結果
        return invocation.proceed();
    }

    private MappedStatement newMappedStatement(MappedStatement ms, Class<Long> longClass) {
        MappedStatement.Builder builder = new MappedStatement.Builder(
                ms.getConfiguration(), ms.getId() + "_count", ms.getSqlSource(), ms.getSqlCommandType()
        );
        ResultMap resultMap = new ResultMap.Builder(ms.getConfiguration(), ms.getId(), longClass, new ArrayList<>(0)).build();
        builder.resource(ms.getResource())
                .fetchSize(ms.getFetchSize())
                .statementType(ms.getStatementType())
                .timeout(ms.getTimeout())
                .parameterMap(ms.getParameterMap())
                .resultSetType(ms.getResultSetType())
                .cache(ms.getCache())
                .flushCacheRequired(ms.isFlushCacheRequired())
                .useCache(ms.isUseCache())
                .resultMaps(Arrays.asList(resultMap));
        if (ms.getKeyProperties() != null && ms.getKeyProperties().length > 0) {
            StringBuilder keyProperties = new StringBuilder();
            for (String keyProperty : ms.getKeyProperties()) {
                keyProperties.append(keyProperty).append(",");
            }
            keyProperties.delete(keyProperties.length() - 1, keyProperties.length());
            builder.keyProperty(keyProperties.toString());
        }
        return builder.build();
    }
}

這是我們今天定義的核心代碼，涉及到的知識點松哥來給大家一個一個剖析。

首先通過 @Intercepts 注解配置攔截器簽名，從 @Signature 的定義中我們可以看到，攔截的是 Executor#query 方法，該方法有一個重載方法，通過 args 指定了方法參數，進而鎖定了重載方法（實際上該方法的另一個重載方法我們沒法攔截，那個是 MyBatis 內部調用的，這里不做討論）。
將查詢操作攔截下來之后，接下來我們的操作主要在 PageInterceptor#intercept 方法中完成，該方法的參數重包含了攔截對象的諸多信息。
通過 invocation.getArgs() 獲取攔截方法的參數，獲取到的是一個數組，正常來說這個數組的長度為 4。數組第一項是一個 MappedStatement，我們在 Mapper.xml 中定義的各種操作節點和 SQL，都被封裝成一個個的 MappedStatement 對象了；數組第二項就是所攔截方法的具體參數，也就是你在 Mapper 接口中定義的方法參數；數組的第三項是一個 RowBounds 對象，我們在 Mapper 接口中定義方法時不一定使用了 RowBounds 對象，如果我們沒有定義 RowBounds 對象，系統會給我們提供一個默認的 RowBounds.DEFAULT；數組第四項則是一個處理返回值的 ResultHandler。
接下來判斷上一步提取到的 rowBounds 對象是否不為 RowBounds.DEFAULT，如果為 RowBounds.DEFAULT，說明用戶不想分頁；如果不為 RowBounds.DEFAULT，則說明用戶想要分頁，如果用戶不想分頁，則直接執行最后的 return invocation.proceed();，讓方法繼續往下走就行了。
如果需要進行分頁，則先從 invocation 對象中取出執行器 Executor、BoundSql 以及通過反射拿出來 BoundSql 中保存的額外參數（如果我們使用了動態 SQL，可能會存在該參數）。BoundSql 中封裝了我們執行的 Sql 以及相關的參數。
接下來判斷 rowBounds 是否是 PageRowBounds 的實例，如果是，說明除了分頁查詢，還想要查詢總記錄數，如果不是，則說明 rowBounds 可能是 RowBounds 實例，此時只要分頁即可，不用查詢總記錄數。
如果需要查詢總記錄數，則首先調用 newMappedStatement 方法構造出一個新的 MappedStatement 對象出來，這個新的 MappedStatement 對象的返回值是 Long 類型的。然后分別創建查詢的 CacheKey、拼接查詢的 countSql，再根據 countSql 構建出 countBoundSql，再將額外參數添加進 countBoundSql 中。最后通過 executor.query 方法完成查詢操作，并將查詢結果賦值給 PageRowBounds 中的 total 屬性。
接下來進行分頁查詢，有了第七步的介紹之后，分頁查詢就很簡單了，這里就不細說了，唯一需要強調的是，當我們啟動了這個分頁插件之后，MyBatis 原生的 RowBounds 內存分頁會變成物理分頁，原因就在這里我們修改了查詢 SQL。
最后將查詢結果返回。

在前面的代碼中，我們一共在兩個地方重新組織了 SQL，一個是查詢總記錄數的時候，另一個則是分頁的時候，都是通過 boundSql.getSql() 獲取到 Mapper.xml 中的 SQL 然后進行改裝，有的小伙伴在 Mapper.xml 中寫 SQL 的時候不注意，結尾可能加上了 ;，這會導致分頁插件重新組裝的 SQL 運行出錯，這點需要注意。松哥在 GitHub 上看到的其他 MyBatis 分頁插件也是一樣的，Mapper.xml 中 SQL 結尾不能有 ;。

如此之后，我們的分頁插件就算是定義成功了。

5.測試

接下來我們對我們的分頁插件進行一個簡單測試。

首先我們需要在全局配置中配置分頁插件，配置方式如下：

<plugins>
    <plugin interceptor="org.javaboy.mybatis03.plugin.PageInterceptor"></plugin>
</plugins>

接下來我們在 Mapper 中定義查詢接口：

public interface UserMapper {
    List<User> getAllUsersByPage(RowBounds rowBounds);
}

接下來定義 UserMapper.xml，如下：

<select id="getAllUsersByPage" resultType="org.javaboy.mybatis03.model.User">
    select * from user
</select>

最后我們進行測試：

@Test
public void test3() {
    UserMapper userMapper = sqlSessionFactory.openSession().getMapper(UserMapper.class);
    List<User> list = userMapper.getAllUsersByPage(new RowBounds(1,2));
    for (User user : list) {
        System.out.println("user = " + user);
    }
}

這里在查詢時，我們使用了 RowBounds 對象，就只會進行分頁，而不會統計總記錄數。需要注意的時，此時的分頁已經不是內存分頁，而是物理分頁了，這點我們從打印出來的 SQL 中也能看到，如下：

可以看到，查詢的時候就已經進行了分頁了。

當然，我們也可以使用 PageRowBounds 進行測試，如下：

@Test
public void test4() {
    UserMapper userMapper = sqlSessionFactory.openSession().getMapper(UserMapper.class);
    PageRowBounds pageRowBounds = new PageRowBounds(1, 2);
    List<User> list = userMapper.getAllUsersByPage(pageRowBounds);
    for (User user : list) {
        System.out.println("user = " + user);
    }
    System.out.println("pageRowBounds.getTotal() = " + pageRowBounds.getTotal());
}

此時通過 pageRowBounds.getTotal() 方法我們就可以獲取到總記錄數。

6.小結

好啦，今天主要和小伙伴們分享了我們如何自己開發一個 MyBatis 插件，插件功能其實都是次要的，最主要是希望小伙伴們能夠理解 MyBatis 的工作流程。

責任編輯：武曉燕來源：江南一點雨

MyBatis 分頁插件