從零開始實現一個MyBatis加解密插件

2022 年 8 月 23 日
筆記
mybatis, spring

作者：vivo 互聯網服務器團隊- Li Gang

本篇文章介紹使用MyBatis插件來實現數據庫字段加解密的過程。

一、需求背景

公司出於安全合規的考慮，需要對明文存儲在數據庫中的部分字段進行加密，防止未經授權的訪問以及個人信息泄漏。

由於項目已停止迭代，改造的成本太大，因此我們選用了MyBatis插件來實現數據庫加解密，保證往數據庫寫入數據時能對指定字段加密，讀取數據時能對指定字段解密。

二、思路解析

2.1 系統架構

對每個需要加密的字段新增密文字段（對業務有侵入），修改數據庫、mapper.xml以及DO對象，通過插件的方式把針對明文/密文字段的加解密進行收口。
自定義Executor對SELECT/UPDATE/INSERT/DELETE等操作的明文字段進行加密並設置到密文字段。
自定義插件ResultSetHandler負責針對查詢結果進行解密，負責對SELECT等操作的密文字段進行解密並設置到明文字段。

2.2 系統流程

新增加解密流程控制開關，分別控制寫入時是只寫原字段/雙寫/只寫加密後的字段，以及讀取時是讀原字段還是加密後的字段。
新增歷史數據加密任務，對歷史數據批量進行加密，寫入到加密後字段。
出於安全上的考慮，流程里還會有一些校驗/補償的任務，這裡不再贅述。

三、方案制定

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件可攔截的類為以下四個。

Executor
StatementHandler
ParameterHandler
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();
    }
}

加密的主體流程如下：

判斷本次調用的方法上是否註解了@TEncrypt。
獲取註解以及在註解上配置的參數。
遍歷parameterObject，找到需要加密的字段。
調用加密方法，得到加密後的值。
將加密後的字段和值寫入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 的理解也加深了。總的來說，這個方案比較輕量，雖然對業務代碼有侵入，但能把影響面控制到最小。

Tags: mybatis spring

從零開始實現一個MyBatis加解密插件

一、需求背景

二、思路解析

2.1 系統架構

2.2 系統流程

三、方案制定

3.1 MyBatis插件簡介

3.2 Spring-MyBatis執行流程

3.3 MyBatis插件的創建時機

3.4 MyBatis插件可攔截類選擇

四、方案實施

五、問題挑戰

5.1 分頁插件自動生成count語句

六、總結

VirMach 便宜 VPS

QNews

從零開始實現一個MyBatis加解密插件

一、需求背景

二、思路解析

2.1 系統架構

2.2 系統流程

三、方案制定

3.1 MyBatis插件簡介

3.2 Spring-MyBatis執行流程

3.3 MyBatis插件的創建時機

3.4 MyBatis插件可攔截類選擇

四、方案實施

五、問題挑戰

5.1 分頁插件自動生成count語句

六、總結

分享此文：

Related Posts

用深度神經網絡解決三體問題，提速一億倍

使用C#編寫一個.NET分析器（一）

關於Redis在windows上運行及fork函數問題

基於SpringSecurity的@PreAuthorize實現自定義權限校驗方法

VirMach 便宜 VPS

QNews

熱門搜尋