MyBatis拦截器终极指南：从原理到企业级实战

在本篇文章中，我们将深入了解如何编写一个 MyBatis 拦截器，并通过一个示例来展示如何在执行数据库操作（如插入或更新）时，自动填充某些字段（例如 createdBy 和 updatedBy）信息。本文将详细讲解拦截器的工作原理、代码示例及其在 MyBatis 项目中的应用。

一、为什么需要数据库操作拦截器？

在典型的企业级应用开发中，我们经常会遇到这样的需求：

需要自动记录数据行的创建时间和修改时间
需要跟踪记录数据操作人
需要实现全局的软删除逻辑
需要对敏感数据进行自动加密
需要实现SQL执行监控和慢查询统计

传统做法是在每个Mapper方法中手动添加这些逻辑，但这样会导致大量重复代码。MyBatis拦截器（Interceptor）正是为了解决这类问题而生，它可以在SQL执行的各个阶段插入自定义逻辑，实现横切关注点的统一管理。

二、MyBatis拦截器核心原理

如果对于MyBatis核心组件功能还不了解的小伙伴们建议先跳到最后一章节:第五节去了解MyBatis核心组件功能再倒回来继续学习！

2.1 拦截器架构

MyBatis采用责任链模式实现拦截器机制，主要拦截点包括：

拦截接口	拦截时机	典型应用场景
Executor	SQL执行前后（增删改查操作）	事务管理、分页处理
StatementHandler	SQL语句构建时	SQL改写、危险操作拦截
ParameterHandler	参数处理时	参数加密、参数校验
ResultSetHandler	结果集处理时	结果解密、数据脱敏

2.2 拦截器生命周期

MyBatis 中的拦截器生命周期较为简单。它的生命周期由 Plugin.wrap() 方法控制，首先会创建代理对象并包装目标对象。拦截器的 intercept 方法在执行目标方法前被调用，拦截器的 plugin 方法用于对目标方法的代理，setProperties 方法用于注入拦截器所需的配置属性。

拦截目标方法调用的顺序：当拦截器装载到 MyBatis 配置中后，每次执行目标方法（如数据库操作的 insert、update）时，都会经过拦截器链。如果多个拦截器存在，它们会按照配置顺序依次执行。可以通过实现Ordered接口或使用@Order注解控制执行顺序：

@Intercepts(...)
@Order(Ordered.HIGHEST_PRECEDENCE)
public class FirstInterceptor implements Interceptor {}

@Intercepts(...)
@Order(Ordered.LOWEST_PRECEDENCE)
public class LastInterceptor implements Interceptor {}

关键接口解析

初始化阶段：通过@Intercepts注解声明拦截目标
代理阶段：通过plugin()方法创建代理对象
执行阶段：intercept()方法处理拦截逻辑
配置阶段：通过XML或Java Config注册拦截器

// 典型拦截器声明
@Intercepts({
    @Signature(type = Executor.class, 
              method = "update",
              args = {MappedStatement.class, Object.class})
})
public class CustomInterceptor implements Interceptor {
    // 实现方法...
}

2.3 代理模式与责任链模式

代理模式（Proxy Pattern）：MyBatis 拦截器本质上是通过代理模式对目标对象进行包装，通过 Plugin.wrap() 方法将拦截器包装在目标对象上，形成一个代理对象。这个代理对象会拦截对目标方法的调用，执行预定的增强逻辑，再将控制权交给目标方法。
责任链模式（Chain of Responsibility Pattern）：MyBatis 的拦截器是按顺序进行链式调用的，多个拦截器会组成一个链，按照声明顺序依次执行，直到所有拦截器都被调用。

三、实战：实现自动化字段填充

3.1 需求分析

实现以下字段的自动填充：

字段名	插入时自动填充	更新时自动填充	数据类型
created_by	✔️	❌	String
created_time	✔️	❌	Date
updated_by	❌	✔️	String
updated_time	❌	✔️	Date
is_deleted	✔️（默认0）	❌	Integer

3.2 完整实现代码解析

package com.wanren.subject.application.interceptor;

import com.wanren.subject.common.util.LoginUtil;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.mapping.SqlCommandType;
import org.apache.ibatis.plugin.*;
import org.springframework.stereotype.Component;

import java.lang.reflect.Field;
import java.util.*;
import java.util.concurrent.Executor;

/**
 *@ClassName MybatisInterceptor
 *@Description 填充createBy,createTime等公共字段的拦截器
 *@Author 彭于晏
 *Date 2025/2/14 0:31
 *Version 1.0
 **/
@Component
@Slf4j
//@Signature指明该拦截器需要拦截哪一个接口的哪一个方法,包括如下
// 接口类型：Executor（拦截执行器方法，负责调用StatementHandler操作数据库）
// StatementHandler（//拦截SQL语法构建处理，直接在数据库执行SQL脚本的对象）、
// ParameterHandler（//拦截参数处理）和ResultSetHandler（//拦截结果集处理，ResultSet结果集对象转换成List类型的集合）
//对应接口中的某一个方法的参数，比如Executor中query方法因为重载原因，有多个，args就是指明参数类型，从而确定是具体哪一个方法。
@Intercepts(@Signature(type = Executor.class,method = "update",args = {
    MappedStatement.class,Object.class
}))
public class MybatisInterceptor implements Interceptor {
    //当被拦截的数据库操作（如查询、插入、更新）发生时，intercept 方法会被调用。
    //invocation的三个方法：Object target = invocation.getTarget();//被代理对象
    //Method method = invocation.getMethod();//代理方法
    //Object[] args = invocation.getArgs();//方法参数
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement mappedStatement = (MappedStatement) invocation.getArgs()[0];
        //MyBatis 中封装 SQL 语句信息的类，表示一个 SQL 映射。MappedStatement 对象包含 SQL 执行所需的所有信息，比如 SQL 命令类型、SQL 语句、参数类型等
        SqlCommandType sqlCommandType = mappedStatement.getSqlCommandType();
        Object parameter = invocation.getArgs()[1];//parameter 是一个 Object 类型，通常是实体类对象
        if(parameter == null){
            //执行目标方法（invocation.proceed()）
            return invocation.proceed();
        }
        //获取当前登录用户的id
        String loginId = LoginUtil.getLoginId();
        if(StringUtils.isBlank(loginId)){
            return invocation.proceed();
        }
        if(sqlCommandType.INSERT == sqlCommandType || sqlCommandType.UPDATE == sqlCommandType){
            replaceEntityProperty(parameter,loginId,sqlCommandType);
        }
        return invocation.proceed();
    }

    private void replaceEntityProperty(Object parameter, String loginId, SqlCommandType sqlCommandType) {
        if(parameter instanceof Map){
            replaceMap((Map) parameter,loginId,sqlCommandType);
        }else{
            replace(parameter,loginId,sqlCommandType);
        }
    }

    private void replace(Object parameter, String loginId, SqlCommandType sqlCommandType) {
        if(SqlCommandType.INSERT == sqlCommandType)
        {
            dealInsert(parameter,loginId);
        }else{
            dealUpdate(parameter,loginId);
        }
    }

    private void dealUpdate(Object parameter, String loginId) {
        Field[] fields = getAllFields(parameter);
        for (Field field : fields) {
            try {
                field.setAccessible(true);
                //parameter是字段名，field是字段的值
                Object o = field.get(parameter);
                //如果该字段不为null，则跳过
                if (Objects.nonNull(o)) {
                    field.setAccessible(false);
                    continue;
                }
                if ("updateBy".equals(field.getName())) {
                    field.set(parameter, loginId);
                    field.setAccessible(false);
                } else if ("updateTime".equals(field.getName())) {
                    field.set(parameter, new Date());
                    field.setAccessible(false);
                } else {
                    field.setAccessible(false);
                }
            }catch (Exception e){
                log.error("dealUpdate.error:{}", e.getMessage(), e);
            }
        }
    }

    private void dealInsert(Object parameter, String loginId) {
        Field[] fields = getAllFields(parameter);
        for(Field field : fields){
            try{
                //Java 语言的私有字段是不可访问的。如果你想访问私有字段（即在类外部访问 private 字段），
                // 你必须调用 setAccessible(true) 来打破 Java 的访问控制，允许访问这些字段。
                field.setAccessible(true);
                Object o = field.get(parameter);
                if (Objects.nonNull(o)) {
                    field.setAccessible(false);
                    continue;
                }
                if("isDeleted".equals(field.getName())){
                    field.set(parameter,0);
                    field.setAccessible(false);
                }
                else if ("createdBy".equals(field.getName())) {
                    field.set(parameter, loginId);
                    field.setAccessible(false);
                } else if ("createdTime".equals(field.getName())) {
                    field.set(parameter, new Date());
                    field.setAccessible(false);
                }else {
                    field.setAccessible(false);
                }
            }catch (Exception e){
                log.error("dealInsert.error:{}", e.getMessage(), e);
            }
        }
    }

    private Field[] getAllFields(Object parameter) {
        Class<?> clazz = parameter.getClass();
        List<Field> fieldList = new ArrayList<>();
        while (clazz != null){
            fieldList.addAll(new ArrayList<>(Arrays.asList(clazz.getDeclaredFields())));
            clazz = clazz.getSuperclass();
        }
        Field[] fields =new Field[fieldList.size()];
        fieldList.toArray(fields);
        return fields;
    }

    private void replaceMap(Map parameter, String loginId, SqlCommandType sqlCommandType) {
        for(Object val : parameter.values()){
            replace(val,loginId,sqlCommandType);
        }
    }

    //插件用于封装目标对象,通过这个方法可以返回目标对象本身，也可以返回一个他的代理，决定
    //是否要进行拦截，从而进一步决定要返回一个怎样的对象
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    //如果我们拦截器需要用到一些变量参数，而且这个参数是支持可配置的，类似Spring中的@Value("${}")从application.properties文件获取自定义变量属性，这个时候我们就可以使用这个方法。
    //在拦截器插件的setProperties方法中进行。这些自定义属性参数会在项目启动的时候被加载。
    @Override
    public void setProperties(Properties properties) {
    }
}

四、扩展应用场景

4.1 敏感数据加密

public Object intercept(Invocation invocation) {
    Object parameter = invocation.getArgs()[1];
    if (parameter instanceof User) {
        User user = (User) parameter;
        user.setPassword(encrypt(user.getPassword()));
    }
    return invocation.proceed();
}

4.2 SQL执行监控

public Object intercept(Invocation invocation) {
    long start = System.nanoTime();
    try {
        return invocation.proceed();
    } finally {
        long cost = (System.nanoTime() - start)/1000000;
        if(cost > 1000){
            log.warn("慢查询警告: {}ms - {}", cost, getSql(invocation));
        }
        
        Metrics.counter("sql.total.count").increment();
        Metrics.timer("sql.execute.time").record(cost, MILLISECONDS);
    }
}

4.3 多租户数据隔离

public void replaceEntityProperty(Object parameter, String tenantId) {
    if (parameter instanceof TenantAware) {
        ((TenantAware) parameter).setTenantId(tenantId);
    }
}