Mybatis源码学习(18)-Mybatis的Plugin模块基础学习

一、Plugin用法简介

注：本小节内容来源于Mybatis官方文档，《传送门》

  MyBatis允许你在已映射语句执行过程中的某一点进行拦截调用。默认情况下，MyBatis 允许使用插件来拦截的方法调用包括：

• Executor (update, query, flushStatements, commit, rollback, getTransaction, close, isClosed)
• ParameterHandler (getParameterObject, setParameters)
• ResultSetHandler (handleResultSets, handleOutputParameters)
• StatementHandler (prepare, parameterize, batch, update, query)

  这些类中方法的细节可以通过查看每个方法的签名来发现，或者直接查看 MyBatis 发行包中的源代码。 如果你想做的不仅仅是监控方法的调用，那么你最好相当了解要重写的方法的行为。 因为如果在试图修改或重写已有方法的行为的时候，你很可能在破坏 MyBatis 的核心模块。 这些都是更低层的类和方法，所以使用插件的时候要特别当心。

  通过 MyBatis 提供的强大机制，使用插件是非常简单的，只需实现 Interceptor 接口，并指定想要拦截的方法签名即可。

// ExamplePlugin.java
@Intercepts({@Signature(
  type= Executor.class,
  method = "update",
  args = {MappedStatement.class,Object.class})})
public class ExamplePlugin implements Interceptor {
  private Properties properties = new Properties();
  public Object intercept(Invocation invocation) throws Throwable {
    // implement pre processing if need
    Object returnObject = invocation.proceed();
    // implement post processing if need
    return returnObject;
  }
  public void setProperties(Properties properties) {
    this.properties = properties;
  }
}

<!-- mybatis-config.xml -->
<plugins>
  <plugin interceptor="org.mybatis.example.ExamplePlugin">
    <property name="someProperty" value="100"/>
  </plugin>
</plugins>

上面的插件将会拦截在 Executor 实例中所有的 “update” 方法调用， 这里的 Executor 是负责执行低层映射语句的内部对象。

覆盖配置类: 除了用插件来修改 MyBatis 核心行为之外，还可以通过完全覆盖配置类来达到目的。只需继承后覆盖其中的每个方法，再把它传递到 SqlSessionFactoryBuilder.build(myConfig) 方法即可。再次重申，这可能会严重影响 MyBatis 的行为，务请慎之又慎。

二、Mybatis中的拦截器实现

1、类结构

  在Mybatis的plugin模块中，采用了责任链设计模式和JDK动态代理。其中使用动态代理来实现拦截器的功能，用来实现增强业务对象的功能；责任链设计模式主要用来实现多拦截器顺序执行的问题。其中动态代理相关知识可以参考《设计模式之代理模式》。
  plugin模块在Mybatis源码中的包路径：org.apache.ibatis.plugin。具体包结构如下图所示：

其中，Intercepts和Signature是注解，通过在实现 Interceptor接口的类添加该注解，实现对指定的类中的特定方法进行拦截；Interceptor是拦截器的接口定义；InterceptorChain是拦截器链的定义；Invocation是对目标对象的封装；Plugin类是代理对象，同时又起到了动态代理对象中的工厂类的作用。下面分别详细介绍各个类：

2、@Intercepts、@Signature注解

@Intercepts注解配合@Signature注解，实现了对指定类中特定方法进行拦截。其中@Intercepts注解定义了一个@Signature注解的集合，即Signature[]数组；@Signature注解用来定义需要拦截的方法，其中type属性指需要拦截的类，method属性指需要拦截的方法名称，args属性指定被拦截方法的参数列表；其实，根据@Signature注解的三个属性，我们就可以唯一确定一个需要拦截的方法了。

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Intercepts {
  Signature[] value();
}

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({})
public @interface Signature {
  Class<?> type();

  String method();

  Class<?>[] args();
}

3、Invocation类

Invocation类是对被代理对象的封装，其中封装了被代理对象实例、目标方法、目标方法的参数列表。同时提供了proceed()方法用来调用目标方法。代码比较简单，如下所示：

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;
  }
  public Object getTarget() {
    return target;
  }
  public Method getMethod() {
    return method;
  }
  public Object[] getArgs() {
    return args;
  }
  /**
   * 执行目标对象方法
   * @return
   * @throws InvocationTargetException
   * @throws IllegalAccessException
   */
  public Object proceed() throws InvocationTargetException, IllegalAccessException {
    return method.invoke(target, args);
  }
}

4、Interceptor 接口

Interceptor接口是Mybatis的plugin模块的核心，所有用户自定义的拦截器，都需要实现该接口。其中，可以被拦截的类在Plugin用法简介中已经描述了。该接口代码如下：

public interface Interceptor {
	/**
	 * 实现拦截逻辑，内部要通过invocation.proceed()显式地推进责任链前进，也就是调用下一个拦截器拦截目标方法。
	 * 
	 * @param invocation
	 * @return
	 * @throws Throwable
	 */
	Object intercept(Invocation invocation) throws Throwable;

	/**
	 * 用当前这个拦截器生成对目标target的代理，实际是通过Plugin.wrap(target,this)
	 * 来完成的，把目标target和拦截器this传给了包装函数。
	 * 
	 * @param target
	 * @return
	 */
	Object plugin(Object target);
	/**
	 * 设置额外的参数，参数配置在拦截器的Properties节点里。
	 * @param properties
	 */
	void setProperties(Properties properties);

}

5、InterceptorChain 类

InterceptorChain 类用来记录用户定义的所有拦截器，底层其实就是用List集合进行了存储。并提供了两个通用方法，1、把拦截器添加到拦截器集合中的方法，即向List集合添加元素，2、为被代理对象添加拦截器的方法，即通过interceptor.plugin()方法实现。具体代码如下：

public class InterceptorChain {
  /**
   * 拦截器存储变量
   */
  private final List<Interceptor> interceptors = new ArrayList<Interceptor>();
  /**
   * 为目标对象添加拦截器
   * 
   * @param target
   * @return
   */
  public Object pluginAll(Object target) {
    for (Interceptor interceptor : interceptors) {
      target = interceptor.plugin(target);
    }
    return target;
  }
  /**
   * 添加拦截器
   * @param interceptor
   */
  public void addInterceptor(Interceptor interceptor) {
    interceptors.add(interceptor);
  }
  
  public List<Interceptor> getInterceptors() {
    return Collections.unmodifiableList(interceptors);
  }

}

6、Plugin类

Plugin类是Mybatis提供的一个工具类，同时实现了InvocationHandler接口。该类的作用有：

• 提供创建动态代理对象的方法，即wrap()方法。
• 实现了InvocationHandler接口，即本身就可以作为一个代理对象。

1. 字段、构造函数

  private final Object target;//被代理对象（目标对象）
  private final Interceptor interceptor;//拦截器
  private final Map<Class<?>, Set<Method>> signatureMap; //记录了@Signature注解中的信息

  private Plugin(Object target, Interceptor interceptor, Map<Class<?>, Set<Method>> signatureMap) {
    this.target = target;
    this.interceptor = interceptor;
    this.signatureMap = signatureMap;
  }

2. wrap()方法
   该方法用于创建动态代理对象。

public static Object wrap(Object target, Interceptor interceptor) {
    Map<Class<?>, Set<Method>> signatureMap = getSignatureMap(interceptor);
    Class<?> type = target.getClass();
    Class<?>[] interfaces = getAllInterfaces(type, signatureMap);
    if (interfaces.length > 0) {
      return Proxy.newProxyInstance(
          type.getClassLoader(),
          interfaces,
          new Plugin(target, interceptor, signatureMap));
    }
    return target;
  }

private static Map<Class<?>, Set<Method>> getSignatureMap(Interceptor interceptor) {
    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());      
    }
    Signature[] sigs = interceptsAnnotation.value();
    Map<Class<?>, Set<Method>> signatureMap = new HashMap<Class<?>, Set<Method>>();
    for (Signature sig : sigs) {
      Set<Method> methods = signatureMap.get(sig.type());
      if (methods == null) {
        methods = new HashSet<Method>();
        signatureMap.put(sig.type(), methods);
      }
      try {
        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;
  }

private static Class<?>[] getAllInterfaces(Class<?> type, Map<Class<?>, Set<Method>> signatureMap) {
    Set<Class<?>> interfaces = new HashSet<Class<?>>();
    while (type != null) {
      for (Class<?> c : type.getInterfaces()) {
        if (signatureMap.containsKey(c)) {
          interfaces.add(c);
        }
      }
      type = type.getSuperclass();
    }
    return interfaces.toArray(new Class<?>[interfaces.size()]);
  }

3. invoke()方法
   该方法其实就是调用被代理对象的方法。首先判断，该方法是否需要被拦截，如果需要就通过interceptor.intercept()方法进行调用，否则直接调用被代理对象的目标方法即可。通过这里我们可以发现，其实我们把需要拦截的方法调用放到了interceptor.intercept()方法中进行了实现，这也是为什么我们要封装Invocation对象的原因，因为这样的话，方便我们统一处理。

@Override
  public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    try {
      Set<Method> 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);
    }
  }

三、总结

  在本章节内容中，我们主要分析了Mybatis中plugin的基本用法和相关源码，下一章节我们分析Mybatis拦截器在初始化过程中是如何加载的，同时分析如何通过Mybatis的拦截器实现一个简易的分页插件。