MyBatis-Plus 字段加密处理最佳实践

概述

MyBatis-Plus 作为 MyBatis 的增强工具，在实际开发中被广泛使用。其中字段加密是一个常见的需求场景，本文主要探讨如何在 MyBatis-Plus 中优雅地实现字段的加密存储和解密查询。

加密处理的基本实现

在 MyBatis-Plus 中，可以通过继承 BaseTypeHandler 来实现字段的加密解密逻辑。典型的加密处理器实现如下：

@MappedJdbcTypes(JdbcType.VARCHAR)
@MappedTypes({String.class})
public class AESEncryptHandler extends BaseTypeHandler<String> {
    
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, 
                                   String parameter, JdbcType jdbcType) throws SQLException {
        // 加密逻辑实现
        String encrypted = EncryptUtil.aesEncrypt(parameter);
        ps.setString(i, encrypted);
    }

    @Override
    public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
        // 解密逻辑实现
        String encrypted = rs.getString(columnName);
        return EncryptUtil.aesDecrypt(encrypted);
    }
    
    // 其他重写方法...
}

实体类配置

在实体类中，通过 @TableField 注解指定字段使用的处理器：

@TableField(value = "system_key", typeHandler = AESEncryptHandler.class)
private String systemKey;

查询时的注意事项

在实际使用中发现，虽然插入操作能自动加密，列表查询能自动解密，但单条数据查询时条件参数不会自动加密。这是因为：

1. MyBatis-Plus 的 LambdaQueryWrapper 在构建查询条件时，默认不会应用字段上配置的 TypeHandler
2. 查询条件的参数直接作为预编译参数传递，没有经过加密处理

解决方案

方案一：使用 apply 方法手动指定

LambdaQueryWrapper<SystemConfig> wrapper = new LambdaQueryWrapper<>();
wrapper.apply("system_key={0,typeHandler=" + 
             AESEncryptHandler.class.getCanonicalName() + "}", systemKey);

这种方式虽然可行，但代码较为冗长，不利于维护。

方案二：自定义 Wrapper 实现

可以继承 LambdaQueryWrapper 实现自动处理加密字段的查询条件：

public class EncryptLambdaQueryWrapper<T> extends LambdaQueryWrapper<T> {
    
    @Override
    public LambdaQueryWrapper<T> eq(boolean condition, SFunction<T, ?> column, Object val) {
        if (condition && val != null) {
            // 获取字段注解
            TableField tableField = getTableField(column);
            if (tableField != null && tableField.typeHandler() != AESEncryptHandler.class) {
                // 应用加密处理
                val = EncryptUtil.aesEncrypt(val.toString());
            }
        }
        return super.eq(condition, column, val);
    }
    
    // 其他需要重写的方法...
}

方案三：AOP 拦截处理

通过 AOP 拦截 Mapper 方法的调用，在查询前对参数进行加密处理：

@Aspect
@Component
public class EncryptAspect {
    
    @Around("execution(* com..mapper.*.*(..))")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        Object[] args = joinPoint.getArgs();
        // 处理参数加密
        processArgsEncrypt(args);
        return joinPoint.proceed(args);
    }
    
    private void processArgsEncrypt(Object[] args) {
        // 实现参数加密逻辑
    }
}

最佳实践建议

1. 对于简单的加密需求，可以采用方案一的方式
2. 对于项目中有大量加密字段的场景，建议采用方案二的自定义 Wrapper
3. 对于需要更灵活控制的场景，方案三的 AOP 方式更为合适
4. 无论采用哪种方案，都应该保证加密解密的对称性
5. 考虑性能影响，特别是大数据量查询时的解密开销

总结

MyBatis-Plus 的字段加密功能虽然强大，但在实际应用中需要注意查询条件的处理。通过合理的架构设计和代码封装，可以实现既安全又易用的加密方案。开发者应根据项目实际情况选择最适合的实现方式，并在团队内部形成统一的加密处理规范。