夜雨聆风写在前面
MyBatis 的插件机制是框架扩展能力的核心。分页插件 PageHelper、性能监控插件、SQL 日志插件……这些都不需要改 MyBatis 源码，只需要实现一个接口、加几个注解，就能在 Executor、StatementHandler、ParameterHandler、ResultSetHandler 的执行链路上"插一脚"。
这篇文章我们拆解插件是怎么被注册、怎么被触发、以及分页插件的底层原理。读完之后你应该能回答：为什么插件只能拦截这四个接口？动态代理 + 责任链是怎么配合工作的？
一、插件的入口：Interceptor 接口
要写一个 MyBatis 插件，只需要实现一个接口：
publicinterfaceInterceptor{Object intercept(Invocation invocation)throws Throwable;default Object plugin(Object target){return Plugin.wrap(target, this); }defaultvoidsetProperties(Properties properties){// NOP }}三个方法：
intercept—— 核心拦截逻辑，插件在这里写自己的代码plugin—— 生成代理对象，默认用Plugin.wrap()setProperties—— 接收 XML 里配置的<property>
以分页插件为例：
@Intercepts({@Signature(type = StatementHandler.class,method= "prepare", args = {Connection.class, Integer.class})})publicclassPaginationInterceptorimplementsInterceptor{@Overridepublic Object intercept(Invocation invocation)throws Throwable { StatementHandler statementHandler = (StatementHandler) invocation.getTarget();// 获取 BoundSql，改写 SQL 添加 LIMIT MetaObject metaObject = SystemMetaObject .forObject(statementHandler); BoundSql boundSql = (BoundSql) metaObject .getValue("delegate.boundSql"); String originalSql = boundSql.getSql(); String pageSql = originalSql + " LIMIT ?, ?"; metaObject.setValue("delegate.boundSql.sql", pageSql);// 继续执行原方法return invocation.proceed(); }}@Intercepts 和 @Signature 注解告诉 MyBatis：我要拦截谁（StatementHandler）的哪个方法（prepare），参数类型是什么（Connection.class, Integer.class）。
二、Plugin.wrap：生成代理对象
Plugin.wrap() 是 MyBatis 插件的核心——它用 JDK 动态代理给目标对象套上一层壳：
publicclassPluginimplementsInvocationHandler{privatefinal Object target;privatefinal Interceptor interceptor;privatefinal Map<Class<?>, Set<Method>> signatureMap;privatePlugin(Object target, Interceptor interceptor, Map<Class<?>, Set<Method>> signatureMap){this.target = target;this.interceptor = interceptor;this.signatureMap = signatureMap; }publicstatic 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; }@Overridepublic 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); } }}Plugin.wrap() 的逻辑：
解析 @Signature注解，生成signatureMap（拦截的接口类 → 方法集合）检查目标对象是否实现了这些接口 如果实现了，生成代理对象；如果没实现，原样返回 invoke()时，判断当前调用的方法是否在signatureMap里如果在 → 调用 interceptor.intercept()（走插件逻辑）如果不在 → 直接调用原方法
这就像给房子加了一层防盗门：门上有猫眼（signatureMap 判断），如果是你认识的人（被拦截的方法），开门检查（执行插件逻辑）；如果不是，直接放行（走原方法）。
getSignatureMap：解析注解
privatestatic Map<Class<?>, Set<Method>> getSignatureMap( Interceptor interceptor) { Intercepts interceptsAnnotation = interceptor.getClass() .getAnnotation(Intercepts.class);if (interceptsAnnotation == null) {thrownew PluginException("No @Intercepts annotation was found in " + "interceptor " + interceptor.getClass()); } Signature[] sigs = interceptsAnnotation.value(); Map<Class<?>, Set<Method>> signatureMap =new HashMap<>();for (Signature sig : sigs) { Set<Method> methods = signatureMap .computeIfAbsent(sig.type(), k -> new HashSet<>());try { Method method = sig.type() .getMethod(sig.method(), sig.args()); methods.add(method); } catch (NoSuchMethodException e) {thrownew PluginException("Could not find method on " + sig.type() + " named " + sig.method() + ". Cause: " + e, e); } }return signatureMap;}解析 @Intercepts 注解，提取每个 @Signature 里声明的接口类型、方法名、参数类型，然后反射获取 Method 对象，存入 Map。
三、InterceptorChain：责任链的组装
单个插件是代理，多个插件就是责任链（Chain of Responsibility）。InterceptorChain 负责把多个插件串起来：
publicclassInterceptorChain{privatefinal List<Interceptor> interceptors =new ArrayList<>();public Object pluginAll(Object target){for (Interceptor interceptor : interceptors) { target = interceptor.plugin(target); }return target; }publicvoidaddInterceptor( Interceptor interceptor){ interceptors.add(interceptor); }public List<Interceptor> getInterceptors(){return Collections.unmodifiableList(interceptors); }}pluginAll() 是核心——遍历所有插件，逐个给目标对象套代理。套了一层又一层，像洋葱一样。
原始对象（Executor/StatementHandler/...） │ ▼Plugin.wrap(原始对象, 插件A) —— 第1层代理 │ ▼Plugin.wrap(第1层代理, 插件B) —— 第2层代理 │ ▼Plugin.wrap(第2层代理, 插件C) —— 第3层代理调用的时候，最外层代理的 invoke 先执行。如果方法被拦截了，进入 interceptor.intercept()；intercept() 里通常最后会调 invocation.proceed()，触发下一层。
这就像俄罗斯套娃：你打开一个，里面还有一个，再打开，里面还有一个。每一层都是一个插件的拦截逻辑。
Invocation：封装调用上下文
publicclassInvocation{privatefinal Object target;privatefinal Method method;privatefinal Object[] args;public Object proceed()throws InvocationTargetException, IllegalAccessException {return method.invoke(target, args); }}Invocation 封装了"被拦截的方法调用"。proceed() 是继续执行原方法（或者下一层代理的 invoke）。插件里通常这样写：
public Object intercept(Invocation invocation)throws Throwable {// 1. 前置逻辑（比如改写 SQL） doSomethingBefore();// 2. 继续执行 Object result = invocation.proceed();// 3. 后置逻辑（比如统计耗时） doSomethingAfter();return result;}四、插件的植入时机：四大组件都被包裹
MyBatis 在创建四大组件时，都会调用 interceptorChain.pluginAll()：
// Configuration.javapublic Executor newExecutor(Transaction transaction, ExecutorType executorType){ executorType = ...; Executor executor;if (...) { executor = new BatchExecutor(this, transaction); } elseif (...) { executor = new ReuseExecutor(this, transaction); } else { executor = new SimpleExecutor(this, transaction); }if (cacheEnabled) { executor = new CachingExecutor(executor); } executor = (Executor) interceptorChain.pluginAll(executor);return executor;}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); statementHandler = (StatementHandler) interceptorChain.pluginAll(statementHandler);return statementHandler;}public ParameterHandler newParameterHandler( MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql){ 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){ ResultSetHandler resultSetHandler =new DefaultResultSetHandler(executor, mappedStatement, parameterHandler, resultHandler, boundSql, rowBounds); resultSetHandler = (ResultSetHandler) interceptorChain.pluginAll(resultSetHandler);return resultSetHandler;}四大组件，每个创建后都会被 pluginAll 包裹。这就是为什么插件可以作用于这四个接口——MyBatis 只在这四个地方植入了插件拦截点。
你可能会问：为什么不能拦截其他方法？比如
SqlSession.insert()？因为
pluginAll只在这四个地方被调用。SqlSession不是通过代理创建的，所以没有拦截点。如果你想拦截SqlSession的方法，只能在外层（比如 Spring AOP）做文章。
五、分页插件的原理：改写 BoundSql
以 PageHelper 为例，它是怎么做到自动分页的？
**拦截 Executor.query**：在查询执行前，提取分页参数（页码、页大小）改写 SQL：把原始 SQL 包装成 count 查询，统计总记录数 再次查询：用改写后的 SQL（带 LIMIT）执行真正的分页查询 封装结果：把结果列表和总记录数封装成 PageInfo 返回
@Intercepts({@Signature(type = Executor.class,method= "query", args = {MappedStatement.class, Object.class,RowBounds.class, ResultHandler.class})})publicclassPageInterceptorimplementsInterceptor{@Overridepublic Object intercept(Invocation invocation)throws Throwable { Object[] args = invocation.getArgs(); MappedStatement ms = (MappedStatement) args[0]; Object parameter = args[1]; RowBounds rowBounds = (RowBounds) args[2];// 检查是否需要分页if (rowBounds instanceof PageRowBounds) {// 1. 执行 count 查询 Long count = executeCount(invocation, ms, parameter);// 2. 改写 SQL，添加 LIMIT BoundSql boundSql = ms.getBoundSql(parameter); String pageSql = boundSql.getSql() + " LIMIT " + rowBounds.getOffset() + ", " + rowBounds.getLimit();// 3. 创建新的 MappedStatement，替换 BoundSql// ... }return invocation.proceed(); }}PageHelper 的巧妙之处在于：它利用了 RowBounds 这个本来用于内存分页的参数，把它变成了物理分页的标志。当 RowBounds 是 PageRowBounds（PageHelper 的自定义子类）时，触发分页逻辑；否则走原来的内存分页。
六、多个插件的执行顺序
插件执行顺序 = 注册顺序。interceptorChain 的 interceptors 列表是按注册顺序排列的，先注册的先执行（最外层），后注册的后执行（最内层）。
<plugins><plugininterceptor="com.example.PluginA"/><plugininterceptor="com.example.PluginB"/><plugininterceptor="com.example.PluginC"/></plugins>执行顺序：
PluginA.intercept() { // A 的前置逻辑 → PluginB.intercept() { // B 的前置逻辑 → PluginC.intercept() { // C 的前置逻辑 → invocation.proceed() → 原始方法 // C 的后置逻辑 } // B 的后置逻辑 } // A 的后置逻辑}这就像三个人排队过安检：A 先检查，然后让 B 检查，B 让 C 检查，C 检查完放行了，然后 C 出来，B 出来，A 出来。每个人都可以在"进去"和"出来"的时候做自己的事。
七、插件机制的局限性
MyBatis 插件虽然强大，但也有明显的限制：
只能拦截四个接口：Executor、StatementHandler、ParameterHandler、ResultSetHandler 只能拦截接口方法：不能拦截类的私有方法 签名匹配必须精确：方法名和参数类型必须完全一致 代理嵌套多了有性能开销：每个插件都套一层代理，调用链变长
八、小结
插件注册 │ ▼InterceptorChain.addInterceptor() │ ▼运行时创建四大组件 │ ├── new Executor() ├── new StatementHandler() ├── new ParameterHandler() └── new ResultSetHandler() │ ▼interceptorChain.pluginAll(target) │ ├── Plugin.wrap(target, 插件A) → 代理A ├── Plugin.wrap(代理A, 插件B) → 代理B └── Plugin.wrap(代理B, 插件C) → 代理C │ ▼方法调用时 │ ├── 代理C.invoke() → 检查 signatureMap → 匹配？→ 插件C.intercept() │ └── invocation.proceed() → 代理B.invoke() │ └── 代理B.invoke() → 检查 → 插件B.intercept() │ └── invocation.proceed() → 代理A.invoke() │ └── ... → 原始方法 └── 不匹配 → method.invoke(target, args) → 直接调用下篇预告
下一篇讲缓存——MyBatis 的一级缓存和二级缓存是怎么工作的？缓存键怎么生成？什么时候会失效？这也是面试最爱问的问题之一。
本系列文章基于 MyBatis 3.5.x 源码，写作时对照源码逐行验证。如果发现有问题的地方，欢迎指正。
