关于mybatis:从零开始实现一个MyBatis加解密插件

作者：vivo 互联网服务器团队 - Li Gang

本篇文章介绍应用 MyBatis 插件来实现数据库字段加解密的过程。

一、需要背景

公司出于平安合规的思考，须要对明文存储在数据库中的局部字段进行加密，避免未经受权的拜访以及个人信息透露。

因为我的项目已进行迭代，革新的老本太大，因而咱们选用了 MyBatis 插件来实现数据库加解密，保障往数据库写入数据时能对指定字段加密，读取数据时能对指定字段解密。

二、思路解析

2.1 零碎架构

1. 对每个须要加密的字段新增密文字段（对业务有侵入），批改数据库、mapper.xml 以及 DO 对象，通过插件的形式把针对明文 / 密文字段的加解密进行收口。
2. 自定义 Executor 对 SELECT/UPDATE/INSERT/DELETE 等操作的明文字段进行加密并设置到密文字段。
3. 自定义插件 ResultSetHandler 负责针对查问后果进行解密，负责对 SELECT 等操作的密文字段进行解密并设置到明文字段。

2.2 零碎流程

1. 新增加解密流程管制开关，别离管制写入时是只写原字段 / 双写 / 只写加密后的字段，以及读取时是读原字段还是加密后的字段。
2. 新增历史数据加密工作，对历史数据批量进行加密，写入到加密后字段。
3. 出于平安上的思考，流程里还会有一些校验 / 弥补的工作，这里不再赘述。

三、计划制订

3.1 MyBatis 插件简介

MyBatis 预留了 org.apache.ibatis.plugin.Interceptor 接口，通过实现该接口，咱们能对 MyBatis 的执行流程进行拦挡，接口的定义如下:

public interface Interceptor {Object intercept(Invocation invocation) throws Throwable;
  Object plugin(Object target);
  void setProperties(Properties properties);
}

其中有三个办法:

• 【intercept】：插件执行的具体流程，传入的 Invocation 是 MyBatis 对被代理的办法的封装。
• 【plugin】：应用以后的 Interceptor 创立代理，通常的实现都是 Plugin.wrap(target, this)，wrap 办法内应用 jdk 创立动静代理对象。
• 【setProperties】：参考下方代码，在 MyBatis 配置文件中配置插件时能够设置参数，在 setProperties 函数中调用 Properties.getProperty(“param1”) 办法能够失去配置的值。

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

在实现 intercept 函数对 MyBatis 的执行流程进行拦挡前，咱们须要应用 @Intercepts 注解指定拦挡的办法。

@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}) })

参考上方代码，咱们能够指定须要拦挡的类和办法。当然咱们不能对任意的对象做拦挡，MyBatis 件可拦挡的类为以下四个。

1. Executor
2. StatementHandler
3. ParameterHandler
4. ResultSetHandler

回到数据库加密的需要，咱们须要从下面四个类里抉择能用来实现入加入密和出参解密的类。在介绍这四个类之前，须要对 MyBatis 的执行流程有肯定的理解。

3.2 Spring-MyBatis 执行流程

（1）Spring 通过 sqlSessionFactoryBean 创立 sqlSessionFactory，在应用 sqlSessionFactoryBean 时，咱们通常会指定 configLocation 和 mapperLocations，来通知 sqlSessionFactoryBean 去哪里读取配置文件以及去哪里读取 mapper 文件。

（2）失去配置文件和 mapper 文件的地位后，别离调用 XmlConfigBuilder.parse() 和 XmlMapperBuilder.parse() 创立 Configuration 和 MappedStatement，Configuration 类顾名思义，寄存的是 MyBatis 所有的配置，而 MappedStatement 类寄存的是每条 SQL 语句的封装，MappedStatement 以 map 的模式寄存到 Configuration 对象中，key 为对应办法的全门路。

（3）Spring 通过 ClassPathMapperScanner 扫描所有的 Mapper 接口，为其创立 BeanDefinition 对象，但因为他们实质上都是没有被实现的接口，所以 Spring 会将他们的 BeanDefinition 的 beanClass 属性批改为 MapperFactorybean。

（4）MapperFactoryBean 也实现了 FactoryBean 接口，Spring 在创立 Bean 时会调用 FactoryBean.getObject() 办法获取 Bean，最终是通过 mapperProxyFactory 的 newInstance 办法为 mapper 接口创立代理，创立代理的形式是 JDK，最终生成的代理对象是 MapperProxy。

（5）调用 mapper 的所有接口实质上调用的都是 MapperProxy.invoke 办法，外部调用 sqlSession 的 insert/update/delete 等各种办法。

MapperMethod.java
public Object execute(SqlSession sqlSession, Object[] args) {
  Object result;
  if (SqlCommandType.INSERT == command.getType()) {Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.insert(command.getName(), param));
  } else if (SqlCommandType.UPDATE == command.getType()) {Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.update(command.getName(), param));
  } else if (SqlCommandType.DELETE == command.getType()) {Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.delete(command.getName(), param));
  } else if (SqlCommandType.SELECT == command.getType()) {if (method.returnsVoid() && method.hasResultHandler()) {executeWithResultHandler(sqlSession, args);
      result = null;
    } else if (method.returnsMany()) {result = executeForMany(sqlSession, args);
    } else if (method.returnsMap()) {result = executeForMap(sqlSession, args);
    } else {Object param = method.convertArgsToSqlCommandParam(args);
      result = sqlSession.selectOne(command.getName(), param);
    }
  } else if (SqlCommandType.FLUSH == command.getType()) {result = sqlSession.flushStatements();
  } else {throw new BindingException("Unknown execution method for:" + command.getName());
  }
  if (result == null && method.getReturnType().isPrimitive() && !method.returnsVoid()) {throw new BindingException("Mapper method'" + command.getName()
        + "attempted to return null from a method with a primitive return type (" + method.getReturnType() + ").");
  }
  return result;
}

（6）SqlSession 能够了解为一次会话，SqlSession 会从 Configuration 中获取对应 MappedStatement，交给 Executor 执行。

DefaultSqlSession.java
@Override
public <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds) {
  try {
    // 从 configuration 对象中应用被调用办法的全门路，获取对应的 MappedStatement
    MappedStatement ms = configuration.getMappedStatement(statement);
    return executor.query(ms, wrapCollection(parameter), rowBounds, Executor.NO_RESULT_HANDLER);
  } catch (Exception e) {throw ExceptionFactory.wrapException("Error querying database.  Cause:" + e, e);
  } finally {ErrorContext.instance().reset();}
}

（7）Executor 会先创立 StatementHandler，StatementHandler 能够了解为是一次语句的执行。

（8）而后 Executor 会获取连贯，具体获取连贯的形式取决于 Datasource 的实现，能够应用连接池等形式获取连贯。

（9）之后调用 StatementHandler.prepare 办法，对应到 JDBC 执行流程中的 Connection.prepareStatement 这一步。

（10）Executor 再调用 StatementHandler 的 parameterize 办法，设置参数，对应到 JDBC 执行流程的 StatementHandler.setXXX() 设置参数，外部会创立 ParameterHandler 办法。

SimpleExecutor.java
@Override
public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
  Statement stmt = null;
  try {Configuration configuration = ms.getConfiguration();
    // 创立 StatementHandler，对应第 7 步
    StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
    // 获取连贯，再调用 conncetion.prepareStatement 创立 prepareStatement，设置参数
    stmt = prepareStatement(handler, ms.getStatementLog());
    // 执行 prepareStatement
    return handler.<E>query(stmt, resultHandler);
  } finally {closeStatement(stmt);
  }
}

（11）再由 ResultSetHandler 解决返回后果，解决 JDBC 的返回值，将其转换为 Java 的对象。

3.3 MyBatis 插件的创立机会

在 Configuration 类中，咱们能看到 newExecutor、newStatementHandler、newParameterHandler、newResultSetHandler 这四个办法，插件的代理类就是在这四个办法中创立的，我以 StatementHandeler 的创立为例：

Configuration.java
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;
}
 
InterceptorChain.java
public Object pluginAll(Object target) {for (Interceptor interceptor : interceptors) {target = interceptor.plugin(target);
  }
  return target;
}

interceptor.plugin 对应到咱们本人实现的 interceptor 里的办法，通常的实现是 Plugin.wrap(target, this);，该办法外部创立代理的形式为 JDK。

3.4 MyBatis 插件可拦挡类抉择

Mybatis 实质上是对 JDBC 执行流程的封装。联合上图咱们简要概括下 Mybatis 这几个可被代理类的职能。

• 【Executor】: 真正执行 SQL 语句的对象，调用 sqlSession 的办法时，实质上都是调用 executor 的办法，还负责获取 connection，创立 StatementHandler。
• 【StatementHandler】: 创立并持有 ParameterHandler 和 ResultSetHandler 对象，操作 JDBC 的 statement 与进行数据库操作。
• 【ParameterHandler】: 解决入参，将 Java 办法上的参数设置到被执行语句中。
• 【ResultSetHandler】: 解决 SQL 语句的执行后果，将返回值转换为 Java 对象。

对于入参的加密，咱们须要在 ParameterHandler 调用 prepareStatement.setXXX() 办法设置参数前，将参数值批改为加密后的参数，这样一看如同拦挡 Executor/StatementHandler/ParameterHandler 都能够。

但实际上呢？因为咱们的并不是在原始字段上做加密，而是新增了一个加密后字段，这会带来什么问题？请看上面这条 mapper.xml 文件中加了加密后字段的动静 SQL：

<select id="selectUserList" resultMap="BaseResultMap" parameterType="com.xxx.internet.demo.entity.UserInfo">
        SELECT
        *
        FROM
        `t_user_info`
        <where>
            <if test="phone != null">
                `phone` = #{phone}
            </if>
<!--            明文字段 -->
            <if test="secret != null">
                AND `secret` = #{secret}
            </if>
<!--            加密后字段 -->
            <if test="secretCiper != null">
                AND `secret_ciper` = #{secretCiper}
            </if>
            <if test="name">
                AND `name` = #{name}
            </if>
        </where>
        ORDER BY `update_time` DESC
    </select>

能够看到这条语句带了动静标签，那必定不能间接交给 JDBC 创立 prepareStatement，须要先将其解析成动态 SQL，而这一步是在 Executor 在调用 StatementHandler.parameterize() 前做的，由 MappedStatementHandler.getBoundSql(Object parameterObject) 函数解析动静标签，生成动态 SQL 语句，这里的 parameterObject 咱们能够临时先将其看成一个 Map，键值别离为参数名和参数值。

那么咱们来看下用 StatementHandler 和 ParameterHandler 做参数加密会有什么问题，在执行 MappedStatementHandler.getBoundSql 时，parameterObject 中并没有写入加密后的参数，在判断标签时必然为否，最初生成的动态 SQL 必然不蕴含加密后的字段，后续不论咱们在 StatementHandler 和 ParameterHandler 中怎么解决 parameterObject，都无奈实现入参的加密。

因而，在入参的加密上咱们只能抉择拦挡 Executor 的 update 和 query 办法。

那么返回值的解密呢？参考流程图，咱们能对 ResultSetHandler 和 Executor 做拦挡，事实也的确如此，在解决返回值这一点上，这两者是等价的，ResultSetHandler.handleResultSet() 的返回值间接透传给 Executor，再由 Executor 透传给 SqlSession，所以两者任选其一就能够。

四、计划施行

在晓得须要拦挡的对象后，就能够开始实现加解密插件了。首先定义一个办法维度的注解。

/**
 * 通过注解来表明，咱们须要对那个字段进行加密
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface TEncrypt {
    /**
     * 加密时从 srcKey 到 destKey
     * @return
     */
    String[] srcKey() default {};
 
    /**
     * 解密时从 destKey 到 srcKey
     * @return
     */
    String[] destKey() default {};}

将该注解打在须要加解密的 DAO 层办法上。

UserMapper.java
public interface UserMapper {@TEncrypt(srcKey = {"secret"}, destKey = {"secretCiper"})
    List<UserInfo> selectUserList(UserInfo userInfo);
    }

批改 xxxMapper.xml 文件

<mapper namespace="com.xxx.internet.demo.mapper.UserMapper">
    <resultMap id="BaseResultMap" type="com.xxx.internet.demo.entity.UserInfo">
        <id column="id" jdbcType="BIGINT" property="id" />
        <id column="phone" jdbcType="VARCHAR" property="phone"/>
        <id column="secret" jdbcType="VARCHAR" property="secret"/>
<!--        加密后映射 -->
        <id column="secret_ciper" jdbcType="VARCHAR" property="secretCiper"/>
        <id column="name" jdbcType="VARCHAR" property="name" />
    </resultMap>
 
    <select id="selectUserList" resultMap="BaseResultMap" parameterType="com.xxx.internet.demo.entity.UserInfo">
        SELECT
        *
        FROM
        `t_user_info`
        <where>
            <if test="phone != null">
                `phone` = #{phone}
            </if>
<!--            明文字段 -->
            <if test="secret != null">
                AND `secret` = #{secret}
            </if>
<!--            加密后字段 -->
            <if test="secretCiper != null">
                AND `secret_ciper` = #{secretCiper}
            </if>
            <if test="name">
                AND `name` = #{name}
            </if>
        </where>
        ORDER BY `update_time` DESCv
    </select>
</mapper>

做完下面的批改，咱们就能够编写加密插件了

@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 {private static final ObjectFactory        DEFAULT_OBJECT_FACTORY         = new DefaultObjectFactory();
 
    private static final ObjectWrapperFactory DEFAULT_OBJECT_WRAPPER_FACTORY = new DefaultObjectWrapperFactory();
 
    private static final ReflectorFactory     REFLECTOR_FACTORY              = new DefaultReflectorFactory();
 
    private static final List<String>         COLLECTION_NAME  = Arrays.asList("list");
 
    private static final String               COUNT_SUFFIX                   = "_COUNT";
 
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
 
        // 获取拦截器拦挡的设置参数对象 DefaultParameterHandler
        final Object[] args = invocation.getArgs();
        MappedStatement mappedStatement = (MappedStatement) args[0];
        Object parameterObject = args[1];
 
        // id 字段对应执行的 SQL 的办法的全门路，蕴含类名和办法名
        String id = mappedStatement.getId();
        String className = id.substring(0, id.lastIndexOf("."));
        String methodName = id.substring(id.lastIndexOf(".") + 1);
 
        // 分页插件会生成一个 count 语句，这个语句的参数也要做解决
        if (methodName.endsWith(COUNT_SUFFIX)) {methodName = methodName.substring(0, methodName.lastIndexOf(COUNT_SUFFIX));
        }
 
        // 动静加载类并获取类中的办法
        final Method[] methods = Class.forName(className).getMethods();
 
        // 遍历类的所有办法并找到此次调用的办法
        for (Method method : methods) {if (method.getName().equalsIgnoreCase(methodName) && method.isAnnotationPresent(TEncrypt.class)) {
 
                // 获取办法上的注解以及注解对应的参数
                TEncrypt paramAnnotation = method.getAnnotation(TEncrypt.class);
 
                // 反对加密的操作，这里只批改参数
                if (parameterObject instanceof Map) {List<String> paramAnnotations = findParams(method);
                    parameterMapHandler((Map) parameterObject, paramAnnotation, mappedStatement.getSqlCommandType(), paramAnnotations);
                } else {encryptParam(parameterObject, paramAnnotation, mappedStatement.getSqlCommandType());
                }
            }
        }
 
        return invocation.proceed();}
}

加密的主体流程如下：

1. 判断本次调用的办法上是否注解了 @TEncrypt。
2. 获取注解以及在注解上配置的参数。
3. 遍历 parameterObject，找到须要加密的字段。
4. 调用加密办法，失去加密后的值。
5. 将加密后的字段和值写入 parameterObject。

难点次要在 parameterObject 的解析，到了 Executor 这一层，parameterObject 曾经不再是简略的 Object[]，而是由 MapperMethod.convertArgsToSqlCommandParam(Object[] args) 办法创立的一个对象，既然要对这个对象做解决，咱们必定得先晓得它的创立过程。

参考上图 parameterObject 的创立过程，加密插件对 parameterObject 的解决实质上是一个逆向的过程。如果是 list，咱们就遍历 list 里的每一个值，如果是 map，咱们就遍历 map 里的每一个值。

失去须要解决的 Object 后，再遍历 Object 里的每个属性，判断是否在 @TEncrypt 注解的 srcKeys 参数中，如果是，则加密再设置到 Object 中。

解密插件的逻辑和加密插件基本一致，这里不再赘述。

五、问题挑战

5.1 分页插件主动生成 count 语句

业务代码里很多中央都用了 com.github.pagehelper 进行物理分页，参考上面的 demo，在应用 PageRowBounds 时，pagehelper 插件会帮咱们获取符合条件的数据总数并设置到 rowBounds 对象的 total 属性中。

PageRowBounds rowBounds = new PageRowBounds(0, 10);
List<User> list = userMapper.selectIf(1, rowBounds);
long total = rowBounds.getTotal();

那么问题来了，外表上看，咱们只执行了 userMapper.selectIf(1, rowBounds) 这一条语句，而 pagehelper 是通过改写 SQL 减少 limit、offset 实现的物理分页，在整个语句的执行过程中没有从数据库里把所有符合条件的数据读出来，那么 pagehelper 是怎么失去数据的总数的呢？

答案是 pagehelper 会再执行一条 count 语句。先不说额定一条执行 count 语句的原理，咱们先看看加了一条 count 语句会导致什么问题。

参考之前的 selectUserList 接口，假如咱们想抉择 secret 为某个值的数据，那么通过加密插件的解决后最终执行的大抵是这样一条语句 “select * from t\_user\_info where secret\_ciper = ? order by update\_time limit ?, ?”。

但因为 pagehelper 还会再执行一条语句，而因为该语句并没有 @TEncrypt 注解，所以是不会被加密插件拦挡的，最终执行的 count 语句是相似这样的: “select count(*) from t\_user\_info where secret = ? order by update_time”。

能够显著的看到第一条语句是应用 secret_ciper 作为查问条件，而 count 语句是应用 secret 作为查问条件，会导致最终失去的数据总量和理论的数据总量不统一。

因而咱们在加密插件的代码里对 count 语句做了非凡解决，因为 pagehelper 新增的 count 语句对应的 mappedStatement 的 id 固定以 ”\_COUNT” 结尾，而这个 id 就是对应的 mapper 里的办法的全门路，举例来说原始语句的 id 是 ”com.xxx.internet.demo.entity.UserInfo.selectUserList”，那么 count 语句的 id 就是 ”com.xxx.internet.demo.entity.UserInfo.selectUserList\_COUNT”，去掉 ”_COUNT” 后咱们再判断对应的办法上有没有注解就能够了。

六、总结

本文介绍了应用 MyBatis 插件实现数据库字段加解密的摸索过程，理论开发过程中须要留神的细节比拟多，整个流程下来我对 MyBatis 的了解也加深了。总的来说，这个计划比拟轻量，尽管对业务代码有侵入，但能把影响面管制到最小。