解密MyBatis拦截器：从插件机制到实战应用

1. MyBatis拦截器基础入门第一次接触MyBatis拦截器时我完全被它强大的功能震撼到了。简单来说拦截器就像是在MyBatis执行SQL过程中的关卡可以在特定时机插入自定义逻辑。想象一下你正在通过一条高速公路SQL执行流程而拦截器就是沿途的收费站、检查站可以在车辆经过时进行收费、检查等操作。MyBatis拦截器最神奇的地方在于它不需要修改框架源码就能扩展功能。这让我想起小时候玩的乐高积木 - 你不需要拆解原有结构只需要在合适的位置添加新模块。具体来说MyBatis允许我们对以下四个核心组件进行拦截Executor执行器负责增删改查操作StatementHandler语句处理器处理SQL语句ParameterHandler参数处理器处理SQL参数ResultSetHandler结果集处理器处理查询结果在实际项目中我经常用拦截器做这些事情监控SQL执行性能找出慢查询自动给敏感数据加密/解密统一添加租户ID实现多租户隔离打印完整的可执行SQL日志2. 拦截器实现原理深度解析2.1 核心接口与注解MyBatis拦截器的实现离不开两个关键元素Interceptor接口和Intercepts注解。当我第一次实现拦截器时发现只需要三步Intercepts({ Signature(type StatementHandler.class, method query, args {Statement.class, ResultHandler.class}) }) public class MyFirstInterceptor implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { System.out.println(拦截开始 invocation.getMethod().getName()); Object result invocation.proceed(); System.out.println(拦截结束); return result; } Override public Object plugin(Object target) { return Plugin.wrap(target, this); } Override public void setProperties(Properties properties) { // 读取配置参数 } }这里有个容易踩的坑plugin方法必须调用Plugin.wrap否则拦截器不会生效。我曾经因为漏写这行代码调试了半天才发现问题。2.2 代理机制揭秘MyBatis拦截器的核心原理是JDK动态代理。当我在调试时发现实际执行的不是原始对象而是一个代理对象时顿时豁然开朗。具体工作流程是这样的MyBatis创建四大组件实例时会调用InterceptorChain.pluginAll每个拦截器通过Plugin.wrap生成代理对象方法调用时先经过代理对象的invoke方法代理对象检查是否需要拦截是则调用拦截器的intercept方法// 简化版的代理逻辑 public Object invoke(Object proxy, Method method, Object[] args) { if (需要拦截该方法) { return interceptor.intercept(new Invocation(target, method, args)); } return method.invoke(target, args); }3. 实战构建SQL监控拦截器3.1 完整实现方案下面分享一个我在生产环境中使用的SQL监控拦截器它可以统计SQL执行时间并自动告警慢查询Intercepts({ Signature(type StatementHandler.class, method query, args {Statement.class, ResultHandler.class}), Signature(type StatementHandler.class, method update, args {Statement.class}) }) public class SqlMonitorInterceptor implements Interceptor { private long slowQueryThreshold 1000; // 默认1秒 Override public Object intercept(Invocation invocation) throws Throwable { long start System.currentTimeMillis(); try { return invocation.proceed(); } finally { long cost System.currentTimeMillis() - start; if (cost slowQueryThreshold) { String sql ((StatementHandler) invocation.getTarget()) .getBoundSql().getSql(); alertSlowQuery(sql, cost); } logSQL(invocation.getMethod().getName(), cost); } } private void alertSlowQuery(String sql, long cost) { // 发送告警邮件/短信 } private void logSQL(String method, long cost) { // 记录执行日志 } Override public void setProperties(Properties properties) { String threshold properties.getProperty(slowQueryThreshold); if (threshold ! null) { this.slowQueryThreshold Long.parseLong(threshold); } } }3.2 配置与使用在MyBatis配置文件中添加plugins plugin interceptorcom.example.SqlMonitorInterceptor property nameslowQueryThreshold value500/ /plugin /plugins如果使用Spring Boot可以通过配置类注册Bean public SqlMonitorInterceptor sqlMonitorInterceptor() { SqlMonitorInterceptor interceptor new SqlMonitorInterceptor(); Properties properties new Properties(); properties.setProperty(slowQueryThreshold, 500); interceptor.setProperties(properties); return interceptor; }4. 高级应用与避坑指南4.1 多拦截器执行顺序当配置多个拦截器时它们的执行顺序很重要。根据我的测试拦截器的执行顺序与配置顺序相反形成一个责任链模式。比如配置了A、B、C三个拦截器实际执行顺序是C→B→A。我曾经遇到一个棘手的问题一个数据脱敏拦截器必须在分页拦截器之后执行。后来通过调整配置顺序解决了这个问题!-- 先执行分页再执行脱敏 -- plugins plugin interceptorcom.example.PageInterceptor/ plugin interceptorcom.example.DataMaskingInterceptor/ /plugins4.2 常见问题排查拦截器不生效检查Intercepts注解配置是否正确确保plugin方法调用了Plugin.wrap确认拦截的是四大组件的方法代理对象无限递归 在intercept方法中直接调用invocation.getTarget()的方法会导致无限递归。正确做法是调用invocation.proceed()。Spring环境下的特殊处理 在Spring Boot中如果通过MapperScan注册Mapper需要确保拦截器在SqlSessionFactory创建前就已经准备好。我通常会在自动配置类上使用AutoConfigureBefore(MybatisAutoConfiguration.class)来确保顺序正确。5. 企业级实战案例5.1 数据权限控制在SAAS系统中我设计了一个数据权限拦截器自动为查询添加租户过滤条件Override public Object intercept(Invocation invocation) throws Throwable { if (invocation.getTarget() instanceof StatementHandler) { StatementHandler handler (StatementHandler) invocation.getTarget(); BoundSql boundSql handler.getBoundSql(); // 修改SQL添加租户条件 String newSql boundSql.getSql() AND tenant_id getCurrentTenantId(); resetSql(handler, boundSql, newSql); } return invocation.proceed(); } private void resetSql(StatementHandler handler, BoundSql boundSql, String newSql) throws NoSuchFieldException, IllegalAccessException { Field field boundSql.getClass().getDeclaredField(sql); field.setAccessible(true); field.set(boundSql, newSql); }5.2 SQL执行日志增强标准的MyBatis日志只能输出带?的SQL我实现了一个拦截器来打印完整SQLOverride public Object intercept(Invocation invocation) throws Throwable { StatementHandler handler (StatementHandler) invocation.getTarget(); BoundSql boundSql handler.getBoundSql(); String completeSql boundSql.getSql(); Object[] params getParameters(handler); // 替换参数占位符 for (Object param : params) { completeSql completeSql.replaceFirst(\\?, param.toString() ); } logger.info(Executing SQL: completeSql); return invocation.proceed(); }这个拦截器在排查生产问题时特别有用可以直接看到执行的完整SQL语句而不是带占位符的模板。