MyBatis 插件原理分析

MyBatis 框架允许用户通过自定义拦截器（Interceptor）的方式改变 SQL 的执行行为，例如：在 SQL 执行时追加分页条件，从而达到简化分页查询的目的，PageHelper分页插件便是通过这个方式实现的。MyBatis 插件的核心原理主要是基于 Java 动态代理机制，拦截 MyBatis 的核心组件（Executor、StatementHandler、ParameterHandler、ResultSetHandler）中方法的执行。

代理模式

先来谈谈 Java 当中的代理模式，在 Java 中，代理模式解决的问题是：在不修改给定目标对象的代码的前提下，在目标对象方法前后添加执行的逻辑。代理又分为静态代理和动态代理。

静态代理

静态代理在编译前就已经确定了代理类，需要手动编写代理类，每个被代理的类都需要一个对应的代理类。

// 定义接口
public interface Service {
    void doSomething();
}

// 目标对象
public class RealService implements Service {
    @Override
    public void doSomething() {
        System.out.println("执行实际业务逻辑...");
    }
}

// 代理对象，不需要改变目标对象的代码，就能对目标对象的方法进行增强
public class StaticProxy implements Service {
    private final Service realService;

    public StaticProxy(Service realService) {
        this.realService = realService;
    }

    @Override
    public void doSomething() {
        System.out.println("静态代理：前置操作");
        realService.doSomething();
        System.out.println("静态代理：后置操作");
    }
}

// 测试
public class StaticProxyTest {
    public static void main(String[] args) {
        //用代理对象执行方法
        Service proxy = new StaticProxy(new RealService());
        proxy.doSomething();
    }
}

动态代理

动态代理在运行时动态生成代理类，无需手动编写代理类。

JDK 动态代理

适用于 面向接口编程（目标类必须实现接口）。

// 目标对象
public class RealService implements Service {
    @Override
    public void doSomething() {
        System.out.println("执行实际业务逻辑...");
    }
}

// 代理逻辑（InvocationHandler）
public class JdkProxyHandler implements InvocationHandler {
    private final Object target;

    public JdkProxyHandler(Object target) {
        this.target = target;
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        System.out.println("JDK 代理：前置操作");
        Object result = method.invoke(target, args);
        System.out.println("JDK 代理：后置操作");
        return result;
    }
}

// 生成代理对象
public class JdkProxyTest {
    public static void main(String[] args) {
        Service realService = new RealService();
        Service proxy = (Service) Proxy.newProxyInstance(realService.getClass().getClassLoader(),
                realService.getClass().getInterfaces(),new JdkProxyHandler(realService));
        proxy.doSomething();
    }
}

CGLIB 代理

基于ASM字节码操作，生成子类并重写方法，不需要目标类实现接口。

// 目标类（没有实现接口）
public class RealService {
    public void doSomething() {
        System.out.println("执行实际业务逻辑...");
    }
}

// CGLIB 代理类
public class CglibProxy implements MethodInterceptor {
    private final Object target;

    public CglibProxy(Object target) {
        this.target = target;
    }

    public Object createProxy() {
        Enhancer enhancer = new Enhancer();
        enhancer.setSuperclass(target.getClass());
        enhancer.setCallback(this);
        return enhancer.create();
    }

    @Override
    public Object intercept(Object obj, Method method, Object[] args, MethodProxy proxy) throws Throwable {
        System.out.println("CGLIB 代理：前置操作");
        Object result = proxy.invokeSuper(obj, args);
        System.out.println("CGLIB 代理：后置操作");
        return result;
    }
}

// 测试
public class CglibProxyTest {
    public static void main(String[] args) {
        RealService realService = new RealService();
        RealService proxy = (RealService) new CglibProxy(realService).createProxy();
        proxy.doSomething();
    }
}

讲完代理的原理，下面我们来谈谈 MyBatis 中插件的使用和实现逻辑。

插件的使用与原理分析

MyBatis 中插件的主要是 JDK 动态代理实现，下面我们来看看如何编写一个插件并分析其原理。

编写插件逻辑

要自定义一个 MyBatis 插件，只需实现 Interceptor 接口，并使用 @Intercepts 注解标注要拦截的方法。例如，下面是一个 SQL 语句打印插件：

// @Intercepts 注解来指定插件拦截哪个类的哪个方法
@Intercepts({@Signature(type = StatementHandler.class,
    method = "prepare",args = {Connection.class, Integer.class})})
//插件需要实现 MyBatis 提供的 Interceptor 接口
public class SqlLogPlugin implements Interceptor {
    //核心方法，用于拦截目标方法的执行，并在此方法中编写增强逻辑。
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        StatementHandler statementHandler = (StatementHandler) invocation.getTarget();
        BoundSql boundSql = statementHandler.getBoundSql();
        System.out.println("SQL: " + boundSql.getSql());
        return invocation.proceed();// 继续执行原始方法
    }
    //该方法用来生成目标对象的代理
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    //用来设置插件的配置信息
    @Override
    public void setProperties(Properties properties) {
        // 读取插件的配置信息
    }
}

插件的注册

在 MyBatis 主配置文件中，可以通过 plugins 标签注册自定义的插件。

<plugins>
    <!-- interceptor 指定了插件的实现类。 -->
    <plugin interceptor="com.example.SqlLogPlugin">
    <!-- <property> 标签用于向插件传递参数，没有的话就不用配置 -->
      <property name="pluginProperty" value="100"/>
    </plugin>
</plugins>

插件的解析

在 MyBatis 启动时，它会解析配置文件中的插件配置，并根据 interceptor 指定的类，利用反射机制创建插件实例，然后将插件加入到拦截器链（InterceptorChain）中。

private void pluginElement(XNode parent) throws Exception {
    if (parent != null) {
      //遍历标签，提取信息
      for (XNode child : parent.getChildren()) {
        String interceptor = child.getStringAttribute("interceptor");
        //获取标签当中的属性
        Properties properties = child.getChildrenAsProperties();
        //利用反射创建实例
        Interceptor interceptorInstance = (Interceptor) resolveClass(interceptor).getDeclaredConstructor().newInstance();
        interceptorInstance.setProperties(properties);
	//往拦截器链中加入拦截器
        configuration.addInterceptor(interceptorInstance);
      }
    }
}

插件的执行流程

当 MyBatis 创建核心组件（如 StatementHandler）时，会调用 InterceptorChain 的 pluginAll() 方法，依次将每个插件应用到目标对象上。

public StatementHandler newStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
    StatementHandler statementHandler = new RoutingStatementHandler(executor, mappedStatement, parameterObject, rowBounds, resultHandler, boundSql);
    //调用 pluginAll() 方法创建代理对象
    statementHandler = (StatementHandler) interceptorChain.pluginAll(statementHandler);
    return statementHandler;
}

pluginAll() 方法会遍历所有的插件，并依次将插件应用到目标对象：

// InterceptorChain.java
public Object pluginAll(Object target) {
    for (Interceptor interceptor : interceptors) {
      target = interceptor.plugin(target); // 每个插件都会包装目标对象，形成链式代理
    }
    return target;
}

每个插件的 plugin() 方法会通过 Plugin.wrap() 方法创建一个动态代理对象（使用 JDK 动态代理）。

// Interceptor.java
default Object plugin(Object target) {
    return Plugin.wrap(target, this);
}
// Plugin.java 实现了 InvocationHandler 接口，并提供了返回代理对象的方法
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;
}

最终，插件会通过 JDK 动态代理的 InvocationHandler 来拦截方法调用。在代理对象调用方法时，invoke() 方法会被触发：

@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)) {
        // 执行拦截逻辑
        //target: 目标对象，即被代理的原始对象（例如 StatementHandler）。
        //method: 当前被调用的方法（即 StatementHandler.prepare()）。
        //args: 当前方法的参数（例如 Connection）
        //Invocation 类的作用是将目标对象、目标方法以及方法参数封装在一起，作为一个统一的对象传递给插件的拦截逻辑。
        //插件可以通过 Invocation 对象来访问这些信息，并在拦截方法时做自定义处理。
        return interceptor.intercept(new Invocation(target, method, args));
      }
      //执行目标对象的方法
      return method.invoke(target, args);
    } catch (Exception e) {
      throw ExceptionUtil.unwrapThrowable(e);
    }
}

总结

MyBatis 插件机制的核心原理基于 JDK 动态代理和拦截器链，插件允许在不修改核心代码的情况下，动态地增强 MyBatis 的执行逻辑。我们可以通过自定义插件来在方法调用前后插入自定义逻辑。

• MyBatis 解析 <plugins> 配置，实例化 SqlLogPlugin。
• 通过 pluginAll() 方法对 StatementHandler 进行代理。
• 当 StatementHandler.prepare() 方法执行时，代理 invoke() 方法被触发。
• 插件拦截 prepare() 方法，打印 SQL 语句。
• 执行 invocation.proceed() 调用原始方法