MyBatis插件原理与责任链模式应用

本文深入剖析了MyBatis插件机制的核心原理——基于JDK动态代理的责任链式拦截，揭示其并非AOP织入或字节码增强，而是通过InterceptorChain在Configuration创建Executor、StatementHandler等四大接口对象时精准包裹，强调“只有经pluginAll()包装的对象才生效”这一关键前提；文章直击开发中常见陷阱：如自定义new对象导致插件失效、@Signature类型匹配错误、ParameterHandler空指针、SQL修改误操作等，并结合调用栈与源码逻辑，阐明多插件注册如何形成嵌套代理链、intercept()中invocation.proceed()为何是责任链传递的命脉，以及为何看似相同的接口方法（如update vs query）拦截效果迥异——本质在于实际执行路径是否落在被代理的接口契约内。读懂它，你才能真正掌控MyBatis插件的生效时机、作用边界与调试方法。

MyBatis Plugin 怎么拦截 Executor、StatementHandler 等四大对象

MyBatis 插件本质是 JDK 动态代理，不是 AOP 织入，也不是字节码增强。它只对四大接口（Executor、StatementHandler、ParameterHandler、ResultSetHandler）的实例做代理，且仅在创建时（如 Configuration.newExecutor()）套一层 Plugin 包装器。

关键点在于：插件生效的前提是目标对象必须经过 InterceptorChain.pluginAll() 调用——这个方法只在 MyBatis 内部对象工厂中被显式调用，比如 Configuration.newStatementHandler() 里会调用 interceptorChain.pluginAll(statementHandler)。如果你自己 new 一个 StatementHandler 实例，插件完全不会生效。

• 四大对象中，只有 Executor 和 StatementHandler 常被拦截；ParameterHandler 和 ResultSetHandler 拦截频率低，且容易因泛型擦除或内部构造方式导致 target 类型判断失效
• 插件类必须实现 Interceptor 接口，并在 plugin(Object target) 方法里判断类型后返回 Plugin.wrap(target, this)，否则代理不成立
• intercept(Invocation invocation) 中调用 invocation.proceed() 才会进入原逻辑；漏掉这句就等于“吃掉”调用，SQL 不会执行

Plugin.wrap() 返回的对象为什么能链式调用

因为 Plugin 是个实现了 InvocationHandler 的代理处理器，它把所有方法调用都转发给 intercept()，而你在 intercept() 里决定是否调用 invocation.proceed() —— 这就是责任链的“传递”动作。

多个插件注册时（如先后 add LogPlugin 和 SlowQueryPlugin），它们会按注册顺序层层包裹：最外层代理 → 第二层代理 → … → 原始对象。所以 invocation.proceed() 实际是触发下一级代理的 invoke()，不是直接调用目标方法。

• 插件注册顺序影响执行顺序：先 add 的插件，intercept() 先执行，但 invocation.proceed() 后执行（因为要等内层返回）
• 如果某个插件的 intercept() 没调 invocation.proceed()，链就断了，后续插件和原始逻辑全跳过
• Plugin 不处理构造函数、静态方法、final 方法——这些根本进不了代理流程

为什么 Executor.update() 拦不到，但 Executor.query() 可以

不是方法名决定能否拦截，而是看该方法是否由被代理对象暴露出来。MyBatis 的 CachingExecutor 或 SimpleExecutor 都实现了 Executor 接口，但部分实现类会把某些操作委托给内部组件（比如批量更新走 BatchExecutor.doFlushStatements()），而这个方法不在 Executor 接口中，自然不会被代理。

更常见的情况是：你写的 intercepts 注解匹配了 update，但实际执行的是 doUpdate（非接口方法），或者被 RoutingStatementHandler 中转后调用的是 PreparedStatementHandler.update() —— 后者属于 StatementHandler 层，得换拦截目标。

• 别迷信接口方法名；用调试确认最终调用栈里实际执行的是哪个类的哪个方法
• @Intercepts 中的 @Signature 必须严格匹配接口类型（如 type = Executor.class），不能写实现类（如 SimpleExecutor.class）
• 事务中的 Executor 可能是 CachingExecutor 包装过的，但它的 update() 方法只是透传，真正逻辑在内层 delegate.update()，此时你需要确保插件也作用于内层 delegate（默认已支持）

插件里访问 SQL 和参数时，StatementHandler 的 parameterHandler 为什么经常为 null

因为 StatementHandler 实例在刚创建时，parameterHandler 字段还没初始化（延迟加载）。比如 RoutingStatementHandler 构造时只设了 delegate 类型，真正初始化 parameterHandler 是在 prepare() 或 parameterize() 阶段。

如果你在 intercept() 里直接取 statementHandler.getParameterHandler()，大概率拿到 null 或未完全初始化的对象——尤其在拦截 prepare() 方法之前。

• 安全做法：在拦截 parameterize(Statement) 或 query(Statement, ResultHandler) 时再取 parameterHandler，此时它已被赋值
• 不要在 intercept() 里强转 statementHandler 为具体实现类（如 PreparedStatementHandler）来绕过接口限制，不同数据库方言下实现类可能不同
• 想改 SQL？用 BoundSql.getSql() + sqlSource 替换，别直接改 statement.toString()——那只是预编译语句模板，不含实际参数

责任链不是黑盒流水线，每一环的 target 是什么、什么时候初始化、有没有被包装过，都得看 MyBatis 源码里那几处 newXXX() 和 pluginAll() 的调用点。漏掉一个初始化时机，就拿不到想要的数据。

今天关于《MyBatis插件原理与责任链模式应用》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！