精盡MyBatis原始碼分析 - 外掛機制
阿新 • • 發佈：2020-11-27
> 該系列文件是本人在學習 Mybatis 的原始碼過程中總結下來的，可能對讀者不太友好，請結合我的原始碼註釋（[Mybatis原始碼分析 GitHub 地址](https://github.com/liu844869663/mybatis-3)、[Mybatis-Spring 原始碼分析 GitHub 地址](https://github.com/liu844869663/spring)、[Spring-Boot-Starter 原始碼分析 GitHub 地址](https://github.com/liu844869663/spring-boot-starter)）進行閱讀
>
> MyBatis 版本：3.5.2
>
> MyBatis-Spring 版本：2.0.3
>
> MyBatis-Spring-Boot-Starter 版本：2.1.4
## 外掛機制
開源框架一般都會提供外掛或其他形式的擴充套件點，供開發者自行擴充套件，增加框架的靈活性
當然，MyBatis 也提供了外掛機制，基於它開發者可以進行擴充套件，對 MyBatis 的功能進行增強，例如實現分頁、SQL分析、監控等功能，本文會對 MyBatis 外掛機制的原理以及如何實現一個自定義的外掛來進行講述
我們在編寫外掛時，除了需要讓外掛類實現 `org.apache.ibatis.plugin.Interceptor` 介面，還需要通過註解標註該外掛的攔截點，也就是外掛需要增強的方法，MyBatis 只提供下面這些類中定義的方法能夠被增強：
- Executor：執行器
- ParameterHandler：引數處理器
- ResultSetHandler：結果集處理器
- StatementHandler：Statement 處理器
### 植入外掛邏輯
在[**《MyBatis的SQL執行過程》**](https://www.cnblogs.com/lifullmoon/p/14015111.html)一系列文件中，有講到在建立Executor、ParameterHandler、ResultSetHandler和StatementHandler物件時，會呼叫`InterceptorChain`的`pluginAll`方法，遍歷所有的外掛，呼叫`Interceptor`外掛的`plugin`方法植入相應的外掛邏輯，所以在 MyBatis 中只有上面的四個物件中的方法可以被增強
程式碼如下：
```java
// Configuration.java
public Executor newExecutor(Transaction transaction, ExecutorType executorType) {
// <1> 獲得執行器型別
executorType = executorType == null ? defaultExecutorType : executorType;
executorType = executorType == null ? ExecutorType.SIMPLE : executorType;
// <2> 建立對應實現的 Executor 物件
Executor executor;
if (ExecutorType.BATCH == executorType) {
executor = new BatchExecutor(this, transaction);
} else if (ExecutorType.REUSE == executorType) {
executor = new ReuseExecutor(this, transaction);
} else {
executor = new SimpleExecutor(this, transaction);
}
// <3> 如果開啟快取，建立 CachingExecutor 物件，進行包裝
if (cacheEnabled) {
executor = new CachingExecutor(executor);
}
// <4> 應用外掛
executor = (Executor) interceptorChain.pluginAll(executor);
return executor;
}
public ParameterHandler newParameterHandler(MappedStatement mappedStatement, Object parameterObject,
BoundSql boundSql) {
// 建立 ParameterHandler 物件
ParameterHandler parameterHandler = mappedStatement.getLang().createParameterHandler(mappedStatement, parameterObject, boundSql);
// 應用外掛
parameterHandler = (ParameterHandler) interceptorChain.pluginAll(parameterHandler);
return parameterHandler;
}
public ResultSetHandler newResultSetHandler(Executor executor, MappedStatement mappedStatement, RowBounds rowBounds,
ParameterHandler parameterHandler, ResultHandler resultHandler, BoundSql boundSql) {
// 建立 DefaultResultSetHandler 物件
ResultSetHandler resultSetHandler = new DefaultResultSetHandler(executor, mappedStatement,
parameterHandler, resultHandler, boundSql, rowBounds);
// 應用外掛
resultSetHandler = (ResultSetHandler) interceptorChain.pluginAll(resultSetHandler);
return resultSetHandler;
}
public StatementHandler newStatementHandler(Executor executor, MappedStatement mappedStatement,
StatementHandler statementHandler = new RoutingStatementHandler(executor, mappedStatement,
parameterObject, rowBounds, resultHandler, boundSql);
// 將 Configuration 全域性配置中的所有外掛應用在 StatementHandler 上面
statementHandler = (StatementHandler) interceptorChain.pluginAll(statementHandler);
return statementHandler;
}
```
### 分頁外掛示例
我們先來看一個簡單的外掛示例，程式碼如下：
```java
@Intercepts({
@Signature(
type = Executor.class,
method = "query",
args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}
)
})
public class ExamplePlugin implements Interceptor {
// Executor的查詢方法：
// public List query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler)
@Override
public Object intercept(Invocation invocation) throws Throwable {
Object[] args = invocation.getArgs();
RowBounds rowBounds = (RowBounds) args[2];
if (rowBounds == RowBounds.DEFAULT) { // 無需分頁
return invocation.proceed();
}
/*
* 將query方法的 RowBounds 入參設定為空物件
* 也就是關閉 MyBatis 內部實現的分頁（邏輯分頁，在拿到查詢結果後再進行分頁的，而不是物理分頁）
*/
args[2] = RowBounds.DEFAULT;
MappedStatement mappedStatement = (MappedStatement) args[0];
BoundSql boundSql = mappedStatement.getBoundSql(args[1]);
// 獲取 SQL 語句，拼接 limit 語句
String sql = boundSql.getSql();
String limit = String.format("LIMIT %d,%d", rowBounds.getOffset(), rowBounds.getLimit());
sql = sql + " " + limit;
// 建立一個 StaticSqlSource 物件
SqlSource sqlSource = new StaticSqlSource(mappedStatement.getConfiguration(), sql, boundSql.getParameterMappings());
// 通過反射獲取並設定 MappedStatement 的 sqlSource 欄位
Field field = MappedStatement.class.getDeclaredField("sqlSource");
field.setAccessible(true);
field.set(mappedStatement, sqlSource);
// 執行被攔截方法
return invocation.proceed();
}
@Override
public Object plugin(Object target) {
// default impl
return Plugin.wrap(target, this);
}
@Override
public void setProperties(Properties properties) {
// default nop
}
}
```
在上面的分頁外掛中，`@Intercepts`和`@Signature`兩個註解指定了增強的方法是`Executor.query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler)`，也就是我們使用到的 Executor 執行資料庫查詢操作的方法
在實現的 `intercept` 方法中，通過 `RowBounds` 引數獲取分頁資訊，並生成相應的 SQL（拼接了 limit） ，並使用該 SQL 作為引數重新建立一個 `StaticSqlSource` 物件，最後通過反射替換 `MappedStatement` 物件中的 `sqlSource` 欄位，這樣就實現了一個簡單的分頁外掛
上面只是一個簡單的示例，實際場景中慎用
### Interceptor
`org.apache.ibatis.plugin.Interceptor`：攔截器介面，程式碼如下：
```java
public interface Interceptor {
/**
* 攔截方法
*
* @param invocation 呼叫資訊
* @return 呼叫結果
* @throws Throwable 若發生異常
*/
Object intercept(Invocation invocation) throws Throwable;
/**
* 應用外掛。如應用成功，則會建立目標物件的代理物件
*
* @param target 目標物件
* @return 應用的結果物件，可以是代理物件，也可以是 target 物件，也可以是任意物件。具體的，看程式碼實現
*/
default Object plugin(Object target) {
return Plugin.wrap(target, this);
}
/**
* 設定攔截器屬性
*
* @param properties 屬性
*/
default void setProperties(Properties properties) {
// NOP
}
}
```
- intercept方法：攔截方法，外掛的增強邏輯
- plugin方法：應用外掛，往目標物件中植入相應的外掛邏輯，如果應用成功則返回一個代理物件（JDK動態代理），否則返回原始物件，預設呼叫`Plugin`的`wrap`方法
- setProperties方法：設定攔截器屬性
### Invocation
`org.apache.ibatis.plugin.Invocation`：被攔截的物件資訊，程式碼如下：
```java
public class Invocation {
/**
* 目標物件
*/
private final Object target;
/**
* 方法
*/
private final Method method;
/**
* 引數
*/
private final Object[] args;
public Invocation(Object target, Method method, Object[] args) {
this.target = target;
this.method = method;
this.args = args;
}
// 省略 getter setter 方法
}
```
### Plugin
`org.apache.ibatis.plugin.Plugin`：實現InvocationHandler介面，用於對攔截的物件進行，一方面提供建立動態代理物件的方法，另一方面實現對指定類的指定方法的攔截處理，MyBatis外掛機制的核心類
#### 構造方法
```java
public class Plugin implements InvocationHandler {
/**
* 目標物件
*/
private final Object target;
/**
* 攔截器
*/
private final Interceptor interceptor;
/**
* 攔截的方法對映
*
* KEY：類
* VALUE：方法集合
*/
private final Map, Set> signatureMap;
private Plugin(Object target, Interceptor interceptor, Map, Set> signatureMap) {
this.target = target;
this.interceptor = interceptor;
this.signatureMap = signatureMap;
}
}
```
#### wrap方法
`wrap(Object target, Interceptor interceptor)`方法，建立目標類的代理物件，方法如下：
```java
public static Object wrap(Object target, Interceptor interceptor) {
// <1> 獲得攔截器中需要攔截的類的方法集合
Map, Set> signatureMap = getSignatureMap(interceptor);
// <2> 獲得目標物件的 Class 物件
Class type = target.getClass();
// <3> 獲得目標物件所有需要被攔截的 Class 物件（父類或者介面）
Class[] interfaces = getAllInterfaces(type, signatureMap);
// <4> 若存在需要被攔截的，則為目標物件的建立一個動態代理物件（JDK 動態代理），代理類為 Plugin 物件
if (interfaces.length > 0) {
// 因為 Plugin 實現了 InvocationHandler 介面，所以可以作為 JDK 動態代理的呼叫處理器
return Proxy.newProxyInstance(type.getClassLoader(), interfaces, new Plugin(target, interceptor, signatureMap));
}
// <5> 如果沒有，則返回原始的目標物件
return target;
}
```
1. 呼叫`getSignatureMap`方法，獲得攔截器中需要攔截的類的方法集合，有就是通過`@Intercepts`和`@Signature`兩個註解指定的增強的方法
2. 獲得目標物件的 Class 物件（父類或者介面）
3. 獲得目標物件所有需要被攔截的 Class 物件
4. 如果需要被攔截，則為目標物件的建立一個動態代理物件（JDK 動態代理），代理類為 `Plugin` 物件，並返回該動態代理物件
5. 否則返回原始的目標物件
#### getSignatureMap方法
`getSignatureMap(Interceptor interceptor)`方法，獲取外掛需要增強的方法，方法如下：
```java
private static Map, Set> getSignatureMap(Interceptor interceptor) {
// 獲取 @Intercepts 註解
Intercepts interceptsAnnotation = interceptor.getClass().getAnnotation(Intercepts.class);
// issue #251
if (interceptsAnnotation == null) {
throw new PluginException( "No @Intercepts annotation was found in interceptor " + interceptor.getClass().getName());
}
// 獲取 @Intercepts 註解中的 @Signature 註解
Signature[] sigs = interceptsAnnotation.value();
Map, Set> signatureMap = new HashMap<>();
for (Signature sig : sigs) {
// 為 @Signature 註解中定義類名建立一個方法陣列
Set methods = signatureMap.computeIfAbsent(sig.type(), k -> new HashSet<>());
try {
// 獲取 @Signature 註解中定義的方法物件
Method method = sig.type().getMethod(sig.method(), sig.args());
methods.add(method);
} catch (NoSuchMethodException e) {
throw new PluginException(
"Could not find method on " + sig.type() + " named " + sig.method() + ". Cause: " + e, e);
}
}
return signatureMap;
}
```
- 通過該外掛上面的`@Intercepts`和`@Signature`註解，獲取到所有需要被攔截的物件中的需要增強的方法
#### getAllInterfaces方法
`getAllInterfaces(Class type, Map, Set> signatureMap)`方法，判斷目標物件是否需要被外掛應用，方法如下：
```java
private static Class[] getAllInterfaces(Class type, Map, Set> signatureMap) {
// 介面的集合
Set> interfaces = new HashSet<>();
// 迴圈遞迴 type 類，機器父類
while (type != null) {
// 遍歷介面集合，若在 signatureMap 中，則新增到 interfaces 中
for (Class c : type.getInterfaces()) {
if (signatureMap.containsKey(c)) {
interfaces.add(c);
}
}
// 獲得父類
type = type.getSuperclass();
}
// 建立介面的陣列
return interfaces.toArray(new Class[interfaces.size()]);
}
```
- 入參`signatureMap`就是`getSignatureMap`方法返回的該外掛需要增強的方法
- 返回存在於`signatureMap`集合中所有目標物件的父類或者介面
#### invoke方法
`invoke(Object proxy, Method method, Object[] args)`方法，動態代理物件的攔截方法，方法如下：
```java
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
try {
// 獲得目標方法所在的類需要被攔截的方法
Set methods = signatureMap.get(method.getDeclaringClass());
if (methods != null && methods.contains(method)) { // 如果被攔截的方法包含當前方法
// 使用外掛攔截該方法進行處理
return interceptor.intercept(new Invocation(target, method, args));
}
// 如果沒有需要被攔截的方法，則呼叫原方法
return method.invoke(target, args);
} catch (Exception e) {
throw ExceptionUtil.unwrapThrowable(e);
}
}
```
1. 獲得目標方法所在的類需要被攔截的方法
2. 如果被攔截的方法包含當前方法，則將當前方法封裝成`Invocation`物件，呼叫`Interceptor`外掛的`intercept`方法，執行外掛邏輯
3. 否則執行原有方法
這樣一來，當你呼叫了目標物件的對應方法時，則會進入該外掛的`intercept`方法，執行外掛邏輯，擴充套件功能
### InterceptorChain
`org.apache.ibatis.plugin.InterceptorChain`：攔截器鏈，用於將所有的攔截器按順序將外掛邏輯植入目標物件，程式碼如下：
```java
public class InterceptorChain {
private final List interceptors = new ArrayList<>();
public Object pluginAll(Object target) {
// 遍歷攔截器集合
for (Interceptor interceptor : interceptors) {
// 呼叫攔截器的 plugin 方法植入相應的外掛邏輯
target = interceptor.plugin(target);
}
return target;
}
public void addInterceptor(Interceptor interceptor) {
interceptors.add(interceptor);
}
public List getInterceptors() {
return Collections.unmodifiableList(interceptors);
}
}
```
配置MyBatis外掛都會儲存在`interceptors`集合中，可以回顧到**《初始化（一）之載入mybatis-config.xml》**的**XMLConfigBuilder**小節的`pluginElement`方法，會將解析到的依次全部新增到`Configuration`的`InterceptorChain`物件中，程式碼如下：
```java
private void pluginElement(XNode parent) throws Exception {
if (parent != null) {
// 遍歷