Mybatis——拦截器Interceptor

Posted 2023-03-30 七海健人

本篇介绍Mybatis拦截器/插件相关知识，包括相关的类及作用、拦截器有哪几种、拦截器可以在Mybatis的执行过程中的哪些节点起作用、拦截器如何使用、相关的API，最后附上代码示例。

1. Mybatis拦截器是什么？一般用途？

MyBatis允许使用者在映射语句执行过程中的某一些指定的节点进行拦截调用，通过织入拦截器，在不同节点修改一些执行过程中的关键属性，从而影响SQL的生成、执行和返回结果，如：来影响Mapper.xml到SQL语句的生成、执行SQL前对预编译的SQL执行参数的修改、SQL执行后返回结果到Mapper接口方法返参POJO对象的类型转换和封装等。

根据上面的对Mybatis拦截器作用的描述，可以分析其可能的用途；最常见的就是Mybatis自带的分页插件PageHelper或Rowbound参数，通过打印实际执行的SQL语句，发现我们的分页查询之前，先执行了COUNT(*)语句查询数量，然后再执行查询时修改了SQL语句即在我们写的SQL语句后拼接上了分页语句LIMIT(offset, pageSize)；

此外，实际工作中，可以使用Mybatis拦截器来做一些数据过滤、数据加密脱敏、SQL执行时间性能监控和告警等；既然要准备使用它，下面先来了解下其原理；

2. Mybatis执行过程

2.1 核心对象

从Mybatis关键代码的来看，MyBatis的主要的核心部件有以下几个：

• Configuration：初始化基础配置，比如MyBatis的别名等，一些重要的类型对象，如插件，映射器，ObjectFactory和typeHandler对象，MyBatis所有的配置信息都维持在Configuration对象之中。
• SqlSessionFactory：SqlSession工厂。
• SqlSession：作为MyBatis工作的主要顶层API，表示和数据库交互的会话，完成必要的数据库增删改查功能。
• Executor：MyBatis的内部执行器，它负责调用StatementHandler操作数据库，并把结果集通过ResultSetHandler进行自动映射，另外，它还处理二级缓存的操作。
• StatementHandler：MyBatis直接在数据库执行SQL脚本的对象。另外它也实现了MyBatis的一级缓存。
• ParameterHandler：负责将用户传递的参数转换成JDBC Statement所需要的参数。是MyBatis实现SQL入参设置的对象。
• ResultSetHandler：负责将JDBC返回的ResultSet结果集对象转换成List类型的集合。是MyBatis把ResultSet集合映射成POJO的接口对象。
• TypeHandler：负责Java数据类型和JDBC数据类型之间的映射和转换。
• MappedStatement：MappedStatement维护了一条<select|update|delete|insert>节点的封装。
• SqlSource ：负责根据用户传递的parameterObject，动态地生成SQL语句，将信息封装到BoundSql对象中，并返回。
• BoundSql：表示动态生成的SQL语句以及相应的参数信息。

2.2 执行过程分析

详细的执行过程可以看数据加密（二）Mybatis拦截器中的3.2 Mybatis整体执行流程，或Mybatis执行流程及关键代码走读；先看下图：

问题：通过mybatis的<if>标签动态修改SQL语句，为什么不能通过ParameterHandler？

通过上面的图可以回答这个问题，在执行ParameterHandler之前，BoundSQL对象已经生成了，即预编译的SQL语句已经生成了；可见，BoundSql生成SQL语句的时机在于 statementHandler 的创建，由MappedStatementHandler.getBoundSql(Object parameterObject)函数解析动态标签，生成静态SQL语句，早于parameterHandler和ResultSetHandler的时机；因此，只能通过影响parameterObject（暂时先将其看成一个Map，键值分别为参数名和参数值）的值，来干预对Mapper.xml标签的解析过程，从而改变生成的BoundSql对象；

3. 如何使用Mybatis拦截器？（使用步骤）

自定义一个mybatis的拦截器步骤包含：

• 定义一个实现org.apache.ibatis.plugin.Interceptor接口的拦截器类，并实现其中的方法。
• 添加@Intercepts注解，写上需要拦截的对象和方法，以及方法参数。
• 在mybatis的全局配置xml中配置插件plugin；对于去xml的Spring工程，显示的注册这个拦截器Bean即可；

3.1 添加注解

MyBatis拦截器默认可以拦截的类型只有四种，即四种接口类型Executor、StatementHandler、ParameterHandler和ResultSetHandler。对于我们的自定义拦截器必须使用MyBatis提供的@Intercepts注解来指明我们要拦截的是四种类型中的哪一种接口。

3.1.1 @Signature注解

@Intercepts	// 描述：标志该类是一个拦截器
@Signature 	// 描述：指明该拦截器需要拦截哪一个接口的哪一个方法

3.1.2 @Signature注解中的type属性

type; // 四种类型接口中的某一个接口，如Executor.class；
method; // 对应接口中的某一个方法名，比如Executor的query方法；
args; // 对应接口中的某一个方法的参数，比如Executor中query方法因为重载原因，有多个，args就是指明参数类型，从而确定是具体哪一个方法；

MyBatis拦截器默认会按顺序拦截以下的四个接口中的所有方法：

org.apache.ibatis.executor.Executor  //拦截执行器方法
org.apache.ibatis.executor.statement.StatementHandler  //拦截SQL语法构建处理
org.apache.ibatis.executor.parameter.ParameterHandler  //拦截参数处理
org.apache.ibatis.executor.resultset.ResultSetHandler  //拦截结果集处理

实际上，具体是拦截这四个接口对应的实现类：

org.apache.ibatis.executor.CachingExecutor
org.apache.ibatis.executor.statement.RoutingStatementHandler
org.apache.ibatis.scripting.defaults.DefaultParameterHandler
org.apache.ibatis.executor.resultset.DefaultResultSetHandler

这几个接口之间的关系大概是这样的：

3.2 实现org.apache.ibatis.plugin.Interceptor接口

实现Interceptor接口，主要是实现下面几个方法：intercept(Invocation invocation)、plugin(Object target) 、setProperties(Properties properties)；

3.2.1 intercept方法

进行拦截的时候要执行的方法。该方法参数Invocation类中有三个字段：

  private final Object target;
  private final Method method;
  private final Object[] args;

可通过这三个字段分别获取下面的信息：

Object target = invocation.getTarget(); //被代理对象
Method method = invocation.getMethod(); //代理方法
Object[] args = invocation.getArgs(); //方法参数

方法实现的结尾处，一般要真正调用被代理类的方法，即"return invocation.proceed();"

3.2.2 plugin方法

插件用于封装目标对象的，通过该方法我们可以返回目标对象本身，也可以返回一个它的代理，可以决定是否要进行拦截进而决定要返回一个什么样的目标对象，官方提供了示例："return Plugin.wrap(target, this);"；

Tips：可以在这个方法中提前进行拦截对象类型判断从而提高性能，如我们仅对Executor拦截，可以这么写：

    @Override
    public Object plugin(Object target) 
        // 只对要拦截制定类型的对象生成代理
        if(target instanceof Executor)
            // 调用插件
            return Plugin.wrap(target, this);
        
        return target;
    

MyBatis拦截器用到责任链模式+动态代理+反射机制；所有可能被拦截的处理类都会生成一个代理类，如果有N个拦截器，就会有N个代理，层层生成动态代理是比较耗性能的。而且虽然能指定插件拦截的位置，但这个是在执行方法时利用反射动态判断的，初始化的时候就是简单的把拦截器插入到了所有可以拦截的地方。所以尽量不要编写不必要的拦截器。另外我们可以在调用插件的地方添加判断，只要是当前拦截器拦截的对象才进行调用，否则直接返回目标对象本身，这样可以减少反射判断的次数，提高性能。

3.2.3 setProperties方法

如果我们拦截器需要用到一些变量参数，而且这个参数是支持可配置的，类似Spring中的@Value("$")从application.properties文件获取自定义变量属性，这个时候我们就可以使用这个方法。

参考下方代码，在Mybatis配置文件中配置插件时可以设置参数，在setProperties函数中调用 Properties.getProperty("param1") 方法可以得到配置的值：

<plugins>
    <plugin interceptor="com.xx.xx.xxxInterceptor">
        <property name="param1" value="value1"/>
    </plugin>
</plugins>

实际上是解析XML，将XML中注册的拦截器的配置带过来；

3.3 代码示例

 这里给一个拦截器的代码示例，如拦截Executor的查询和更新方法：

@Intercepts(@Signature(type = Executor.class, method = "update", args = MappedStatement.class, Object.class),
        @Signature(type = Executor.class, method = "query", args = MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class))
public class ExecutorEncryptInterceptor implements Interceptor 
 
    /* ... */
	
	Properties properties = null;
	
	/**
     * 拦截方法逻辑
     * 这里主要是通过反射去获取要执行的SQL相关信息，然后进行操作
     */
    @Override
    public Object intercept(Invocation invocation) throws Throwable 
 
		Object target = invocation.getTarget(); //被代理对象
        Method method = invocation.getMethod(); //代理方法
        Object[] args = invocation.getArgs(); //方法参数
		
		MappedStatement mappedStatement = (MappedStatement) args[0];
        Object parameterObject = args[1];
		
        // do something ...方法拦截前执行代码块
		
        Object result = invocation.proceed();
		
        // do something ...方法拦截后执行代码块
		
        return result;

    
 
    /**
     * 生成MyBatis拦截器代理对象
     */
    @Override
    public Object plugin(Object target) 
        if(target instanceof Executor)
            // 调用插件
            return Plugin.wrap(target, this);
        
        return target;
    
 
    /**
     * 设置插件属性（直接通过Spring的方式获取属性，所以这个方法一般也用不到）
     * 项目启动的时候数据就会被加载
     */
    @Override
    public void setProperties(Properties properties) 
        // 赋值成员变量，在其他方法使用
        this.properties = properties;
    
 
   /* ... */
   

参考：

MyBatis拦截器原理介绍 - 简书

MyBatis拦截器使用方法总结

Mybatis那些事-拦截器(Plugin+Interceptor)

作者：yhjyumi的专栏

 Mybatis的拦截器实现机制,使用的是JDK的InvocationHandler.

当我们调用ParameterHandler,ResultSetHandler,StatementHandler,Executor的对象的时候,
实际上使用的是Plugin这个代理类的对象,这个类实现了InvocationHandler接口.
接下来我们就知道了,在调用上述被代理类的方法的时候,就会执行Plugin的invoke方法.
Plugin在invoke方法中根据@Intercepts的配置信息(方法名,参数等)动态判断是否需要拦截该方法.
再然后使用需要拦截的方法Method封装成Invocation,并调用Interceptor的proceed方法.
这样我们就达到了拦截目标方法的结果.
例如Executor的执行大概是这样的流程:
拦截器代理类对象->拦截器->目标方法
Executor->Plugin->Interceptor->Invocation
Executor.Method->Plugin.invoke->Interceptor.intercept->Invocation.proceed->method.invoke


注解
@Intercepts 在实现Interceptor接口的类声明,使该类注册成为拦截器
  Signature[] value//定义需要拦截哪些类,哪些方法
@Signature 定义哪些类(4种)，方法，参数需要被拦截
  Class<?> type()//ParameterHandler,ResultSetHandler,StatementHandler,Executor
  String method()//
  Class<?>[] args()//

接口
Interceptor 实现拦截器的接口

类
InterceptorChain 拦截器链,保存了Mybatis配置的所有拦截器,保存在Configuration
  List<Interceptor> interceptors//拦截器

Invocation 类方法的一个封装,在拦截器中就是被调用的目标方法
  Object target//调用的对象
  Method method//调用的方法
  Object[] args//参数

Plugin 插件,其实就是ParameterHandler,ResultSetHandler,StatementHandler,Executor的代理类(Mybatis使用的JDK代理实现拦截器),实现了InvocationHandler接口
 Object target//被代理的目标对象
 Interceptor interceptor//拦截器
 Map<Class<?>, Set<Method>> signatureMap//接口需要拦截的方法(一对多,每个接口对应多个方法)
 //
 wrap(Object target, Interceptor interceptor)//把拦截器对象封装成Plugin代理对象.
 invoke(Object proxy, Method method, Object[] args)//
 

使用例子
1.写一个类,并且实现Interceptor接口
2.在上述类使用@Intercepts注解,配置拦截信息
3.在配置文件配置插件
@Intercepts({ @Signature(type = Executor.class, method = "query", args = { MappedStatement.class, Object.class,
        RowBounds.class, ResultHandler.class }) })
public class MyInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        return invocation.proceed();
    }
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    @Override
    public void setProperties(Properties properties) {
        // TODO Auto-generated method stub

    }
}
配置文件加入
<plugins>
    <plugin interceptor="weber.mybatis.plugin.MyInterceptor" />
</plugins>

 

加入测试代码

 

[java] view plain copy

 

1. public static void main(String[] args) throws IOException {  
2.   
3.         String resource = "conf.xml";  
4.   
5.         InputStream is = Test1.class.getClassLoader().getResourceAsStream(resource);  
6.   
7.         SqlSessionFactory sessionFactory = new SqlSessionFactoryBuilder().build(is);  
8.   
9.         SqlSession session = sessionFactory.openSession();  
10.   
11.         // User user = session.selectOne("weber.mybatis.mapper.getUser", 1);  
12.         User userObj = new User();  
13.         userObj.setId(123);  
14.         session.selectList("weber.mybatis.mapper.searchByUser", userObj);  
15.   
16.         // UserMapper mapper = session.getMapper(UserMapper.class);  
17.   
18.         // mapper.selectAll();  
19.   
20.         // System.out.println(user);  
21.     }  

 

 

开启debug模式,我们将看到Plugin是如何实现代理的.

当代码执行到下图红色部分的时候

将直接跳到下图!所以,我们此时的executor不是CachingExecutor对象,而是Plugin代理对象.

此时的method,就是被调用的目标方法如下:

 

最后附上源码注释

 

[java] view plain copy

 

1. /** 
2.  * @author Clinton Begin 
3.  */  
4. //Plugin是JDK动态代理类  
5. public class Plugin implements InvocationHandler {  
6.   
7.   private Object target;//目标对象(ParameterHandler,ResultSetHandler,StatementHandler,Executor)  
8.   private Interceptor interceptor;//被代理的拦截器  
9.   //目标类需要拦截的方法缓存.因为一个拦截器可以拦截多个类,一个类可以拦截多个方法.  
10.   //所以用Map + Set的数据结构存储  
11.   private Map<Class<?>, Set<Method>> signatureMap;//保存每个拦截器的@signature的配置信息  
12.   
13.   private Plugin(Object target, Interceptor interceptor, Map<Class<?>, Set<Method>> signatureMap) {  
14.     this.target = target;  
15.     this.interceptor = interceptor;  
16.     this.signatureMap = signatureMap;  
17.   }  
18.   //把目标对象和拦截器封装成Plugin代理类实例.  
19.   public static Object wrap(Object target, Interceptor interceptor) {  
20.     Map<Class<?>, Set<Method>> signatureMap = getSignatureMap(interceptor);//获取拦截器的拦截信息(需要拦截的类和方法)  
21.     Class<?> type = target.getClass();  
22.     Class<?>[] interfaces = getAllInterfaces(type, signatureMap);//Proxy代理只能代理接口  
23.     if (interfaces.length > 0) {  
24.       return Proxy.newProxyInstance(  
25.           type.getClassLoader(),  
26.           interfaces,  
27.           new Plugin(target, interceptor, signatureMap));//Plugin作为代理类,但是实际业务是由Interceptor拦截器完成的.  
28.     }  
29.     return target;  
30.   }  
31.   
32.   @Override  
33.    //proxy,类代理的对象,例如CachingExecutor对象  
34.   public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {  
35.     try {//从这里代码看到,会拦截所有的Executor方法,动态的去判断拦截器要不要去拦截.所以要小心使用拦截器,会影响性能.  
36.       Set<Method> methods = signatureMap.get(method.getDeclaringClass());  
37.       if (methods != null && methods.contains(method)) {  
38.         //Invocation是目标对象,目标对象需要拦截的方法,我拦截方法的参数的封装.  
39.         return interceptor.intercept(new Invocation(target, method, args));//调用拦截器实现拦截  
40.       }  
41.       return method.invoke(target, args);//不需要拦截的方法直接放行  
42.     } catch (Exception e) {  
43.       throw ExceptionUtil.unwrapThrowable(e);  
44.     }  
45.   }  
46.   
47.   private static Map<Class<?>, Set<Method>> getSignatureMap(Interceptor interceptor) {  
48.     Intercepts interceptsAnnotation = interceptor.getClass().getAnnotation(Intercepts.class);//获取拦截器注解@Signature  
49.     // issue #251  
50.     if (interceptsAnnotation == null) {  
51.       throw new PluginException("No @Intercepts annotation was found in interceptor " + interceptor.getClass().getName());        
52.     }  
53.     Signature[] sigs = interceptsAnnotation.value();//一个Signature表示一个拦截类型  
54.     //保存需要拦截类的信息,class作为key, 需要拦截类的方法作为value集合Set保存.一个拦截器可以拦截一个类中多个方法  
55.     Map<Class<?>, Set<Method>> signatureMap = new HashMap<Class<?>, Set<Method>>();  
56.     for (Signature sig : sigs) {  
57.       Set<Method> methods = signatureMap.get(sig.type());  
58.       if (methods == null) {  
59.         methods = new HashSet<Method>();  
60.         signatureMap.put(sig.type(), methods);  
61.       }  
62.       try {  
63.         Method method = sig.type().getMethod(sig.method(), sig.args());//获取需要拦截的方法  
64.         methods.add(method);  
65.       } catch (NoSuchMethodException e) {  
66.         throw new PluginException("Could not find method on " + sig.type() + " named " + sig.method() + ". Cause: " + e, e);  
67.       }  
68.     }  
69.     return signatureMap;  
70.   }  
71.   
72.   private static Class<?>[] getAllInterfaces(Class<?> type, Map<Class<?>, Set<Method>> signatureMap) {  
73.     Set<Class<?>> interfaces = new HashSet<Class<?>>();  
74.     while (type != null) {  
75.       for (Class<?> c : type.getInterfaces()) {  
76.         if (signatureMap.containsKey(c)) {  
77.           interfaces.add(c);  
78.         }  
79.       }  
80.       type = type.getSuperclass();  
81.     }  
82.     return interfaces.toArray(new Class<?>[interfaces.size()]);  
83.   }  
84.   
85. }  

 

[java] view plain copy

 

1. /** 
2.  * @author Clinton Begin 
3.  */  
4. //InterceptorChain里保存了所有的拦截器，它在mybatis初始化的时候创建。存在Configuration中  
5. public class InterceptorChain {  
6.   
7.   private final List<Interceptor> interceptors = new ArrayList<Interceptor>();  
8.   
9.   //每一个拦截器对目标类都进行一次代理(也就是会出现代理的代理的代理.....有点拗口)  
10.   public Object pluginAll(Object target) {  
11.     for (Interceptor interceptor : interceptors) {  
12.       target = interceptor.plugin(target);  
13.     }  
14.     return target;  
15.   }  
16.   
17.   public void addInterceptor(Interceptor interceptor) {  
18.     interceptors.add(interceptor);  
19.   }  
20.     
21.   public List<Interceptor> getInterceptors() {  
22.     return Collections.unmodifiableList(interceptors);  
23.   }  
24.   
25. }  

 

[java] view plain copy

 

1. /** 
2.  * @author Clinton Begin 
3.  */  
4. public interface Interceptor {  
5.   
6.   Object intercept(Invocation invocation) throws Throwable;//拦截方法,在这里处理拦截器的业务逻辑  
7.   
8.   Object plugin(Object target);//把目标对象封装成Plugin对象  
9.   
10.   void setProperties(Properties properties);  
11.   
12. }