MyBatis-Plus数据加密实战：如何用注解+拦截器保护敏感字段（附完整代码）
在今天的应用开发中，数据安全早已不是一道选择题，而是关乎产品信誉和用户信任的必答题。无论是处理用户的身份证号、手机号，还是管理金融交易中的金额、账户信息，一旦这些敏感数据在存储或传输环节出现纰漏，后果往往不堪设想。作为Java生态中广受欢迎的ORM增强工具，MyBatis-Plus本身并未内置一套开箱即用的字段级加密方案，这恰恰给了我们一个机会，去构建一套既贴合业务需求，又具备良好扩展性的安全防护层。
这篇文章，我想和你分享的，不是教科书式的理论，而是一套经过实际项目锤炼的、基于MyBatis-Plus的字段加解密实战方案。我们将绕过那些复杂的、需要改造数据库驱动或重写SQL解析器的重型方案，聚焦于一种更为轻巧、侵入性更低的方式：自定义注解配合MyBatis拦截器。这种方式的核心思想是，在数据“入库”和“出库”的关键节点进行拦截，对标记了特定注解的字段进行自动的加密和解密操作。对于开发者而言，几乎是无感的——你只需要在实体类上打上几个注解，剩下的脏活累活，框架替你干了。
接下来，我会带你从零开始，一步步拆解这套机制的每一个齿轮是如何咬合的。我们会设计自己的注解、编写加解密工具、实现核心的拦截器逻辑，并最终将它们组装成一个可复用的组件。更重要的是，我会分享在实现过程中遇到的那些“坑”，以及如何让这套方案不仅能工作，还能工作得优雅、高效。无论你是正在为即将上线的新项目寻找数据安全方案，还是希望对现有系统进行安全加固，相信接下来的内容都能给你带来直接的启发和可落地的代码。
1. 架构设计与核心思想：为何选择拦截器？
在动手写代码之前，我们得先想清楚为什么要走“注解+拦截器”这条路。市面上实现数据字段加密的方案不少，各有优劣，理解我们选择的背景，能帮助你在未来遇到更复杂场景时做出更好的决策。
一种常见的思路是在业务层进行加解密。即在Service层，保存数据前手动调用加密方法，查询出数据后手动调用解密方法。这种方法直白，但缺点也很明显：侵入性强，容易遗漏。每个涉及敏感字段的增删改查方法都需要添加加解密代码，不仅增加了开发工作量，更可怕的是，一旦有某个方法被遗忘，就会导致明文数据被意外存入数据库，形成安全漏洞。另一种思路是使用数据库自身的加密功能，如透明数据加密（TDE）。这固然强大，但通常依赖于特定的数据库版本（如企业版），且加密粒度是表空间或整个数据库文件，无法做到针对个别字段的灵活控制，同时也将安全策略与特定的数据库产品深度绑定。
相比之下，在MyBatis/MyBatis-Plus的框架层面，通过拦截器实现字段加解密，具有显著优势：
- 无侵入性：业务代码完全感知不到加密的存在。实体类就是普通的POJO，Service层进行常规的
save、update、select操作即可。 - 集中管理：加解密逻辑被封装在少数几个拦截器类中，一处修改，处处生效。安全策略的调整和维护变得非常简单。
- 灵活性高：我们可以通过自定义注解，精确控制哪些实体类、哪些字段需要被加密。不同字段甚至可以采用不同的加密算法（如手机号用AES，金额用自定义算法）。
- 与框架生态融合好：MyBatis的插件（拦截器）机制非常成熟和稳定，我们是在其设计模式内进行扩展，兼容性和稳定性有保障。
这套方案的核心流程可以概括为两条主线：
- 写入（INSERT/UPDATE）流程：MyBatis执行器准备将参数设置到SQL语句时，被我们的
EncryptInterceptor拦截。拦截器检查参数对象，如果其类上标记了特定注解，则遍历其字段，对标记了加密注解的字段值进行加密，然后再放行。 - 读取（SELECT）流程：MyBatis将数据库结果集映射为Java对象后，在返回给调用者之前，被我们的
DecryptInterceptor拦截。拦截器检查结果对象，对标记了加密注解的字段值进行解密，然后将解密后的对象返回。
整个过程中，数据库里存储的始终是密文，而内存中的Java对象则是“纯净”的明文。业务逻辑在明文的维度上运作，安全在数据持久化的维度上得到保障。
2. 基石：构建加解密工具与注解定义
任何加密方案都离不开加解密算法的支撑。为了保持示例的清晰和可运行，我们这里使用Hutool工具包提供的AES对称加密工具。在实际生产环境中，密钥的管理（如从配置中心、KMS服务获取）是重中之重，绝不能像示例中这样硬编码在代码里。
首先，引入必要的依赖（以Maven为例）：
<dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-crypto</artifactId> <version>5.8.22</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.6</version> </dependency>接下来，我们创建两个核心注解。注解的作用是“打标记”，告诉拦截器：“嘿，这个类/这个字段需要你特殊关照一下。”
import java.lang.annotation.*; /** * 标记需要加解密的实体类。 * 被此注解标注的类，其内部被@EncryptedField标注的字段会在数据库操作时被自动处理。 */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface EncryptedTable { }import java.lang.annotation.*; /** * 标记需要加解密的字段。 * 此注解必须用在被@EncryptedTable标注的类的字段上。 */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.FIELD) public @interface EncryptedField { }注解定义好了，我们就需要一个强大的“工具箱”来执行实际的加解密操作。这个工具类需要能处理不同类型的字段（String, BigDecimal等），并且能智能地识别注解。
import cn.hutool.core.util.ObjectUtil; import cn.hutool.crypto.SecureUtil; import cn.hutool.crypto.symmetric.AES; import org.springframework.core.annotation.AnnotationUtils; import java.lang.reflect.Field; import java.math.BigDecimal; import java.nio.charset.StandardCharsets; import java.util.Objects; /** * 加解密核心工具类。 * 注意：此处密钥为示例，实际项目必须从安全配置源获取！ */ public class EncryptDecryptUtils { // 示例密钥，生产环境务必使用安全方式管理！ private static final byte[] KEYS = "YourSuperSecretKey16".getBytes(StandardCharsets.UTF_8); private static final AES AES_INSTANCE = SecureUtil.aes(KEYS); /** * 加密对象。 * 检查对象类是否被@EncryptedTable标注，如果是，则加密其下所有被@EncryptedField标注的字段。 */ public static void encryptObject(Object parameterObject) throws IllegalAccessException { if (ObjectUtil.isEmpty(parameterObject)) { return; } Class<?> clazz = parameterObject.getClass(); EncryptedTable tableAnnotation = AnnotationUtils.findAnnotation(clazz, EncryptedTable.class); if (Objects.nonNull(tableAnnotation)) { Field[] fields = clazz.getDeclaredFields(); for (Field field : fields) { if (field.isAnnotationPresent(EncryptedField.class)) { encryptField(field, parameterObject); } } } } /** * 解密对象。 * 逻辑与加密对称，将密文字段还原为明文。 */ public static void decryptObject(Object resultObject) throws IllegalAccessException { if (ObjectUtil.isEmpty(resultObject)) { return; } Class<?> clazz = resultObject.getClass(); // 同样需要检查类注解，确保只处理我们标记的类 EncryptedTable tableAnnotation = AnnotationUtils.findAnnotation(clazz, EncryptedTable.class); if (Objects.nonNull(tableAnnotation)) { Field[] fields = clazz.getDeclaredFields(); for (Field field : fields) { if (field.isAnnotationPresent(EncryptedField.class)) { decryptField(field, resultObject); } } } } /** * 加密单个字段。 * 这里演示了如何处理String和BigDecimal类型。 * 你可以根据需要扩展其他类型（如Integer、Long，或自定义对象）。 */ private static void encryptField(Field field, Object targetObj) throws IllegalAccessException { field.setAccessible(true); Object originalValue = field.get(targetObj); if (originalValue == null) { return; // 空值不处理 } if (originalValue instanceof String) { String strValue = (String) originalValue; // 使用AES加密，输出Hex字符串存储 String encryptedHex = AES_INSTANCE.encryptHex(strValue); field.set(targetObj, encryptedHex); } else if (originalValue instanceof BigDecimal) { // 对于金额等数值，有时需要特殊处理。这里是一个简单示例：放大并偏移后存储。 // 注意：这并非强加密，生产环境应对金额使用更安全的算法或保持String加密。 BigDecimal decimalValue = (BigDecimal) originalValue; // 示例：将金额放大10000倍并加上一个固定偏移量后转为Long存储 long transformedValue = decimalValue.multiply(BigDecimal.valueOf(10000)) .add(BigDecimal.valueOf(1234567890L)) .longValue(); field.set(targetObj, BigDecimal.valueOf(transformedValue)); } // 可以继续添加 else if 处理其他类型 } /** * 解密单个字段。 * 逻辑与加密过程严格互逆。 */ private static void decryptField(Field field, Object targetObj) throws IllegalAccessException { field.setAccessible(true); Object encryptedValue = field.get(targetObj); if (encryptedValue == null) { return; } if (encryptedValue instanceof String) { String encryptedHex = (String) encryptedValue; try { // 尝试解密，如果解密失败（可能是历史明文数据），则直接返回原值 String decryptedStr = AES_INSTANCE.decryptStr(encryptedHex); field.set(targetObj, decryptedStr); } catch (Exception e) { // 记录日志，但不要抛出异常，避免影响查询。这里选择原样返回。 // log.warn("字段解密失败，返回原始值。字段: {}, 值: {}", field.getName(), encryptedHex); field.set(targetObj, encryptedHex); } } else if (encryptedValue instanceof BigDecimal) { BigDecimal transformedValue = (BigDecimal) encryptedValue; // 逆向操作：先转Long，减去偏移量，再缩小10000倍 long longValue = transformedValue.longValue(); BigDecimal originalDecimal = BigDecimal.valueOf(longValue) .subtract(BigDecimal.valueOf(1234567890L)) .divide(BigDecimal.valueOf(10000)); field.set(targetObj, originalDecimal); } } }注意：上面的
BigDecimal处理仅仅是一个演示性质的变形，并非密码学意义上的加密。对于金融等敏感数据，建议将其转换为String后使用强加密算法（如AES）处理，或者寻求专业的加密库。密钥KEYS的硬编码是严重的安全反模式，务必通过环境变量、配置中心或专业的密钥管理服务（KMS）来获取。
3. 核心引擎：实现MyBatis加密与解密拦截器
工具和注解准备就绪，现在我们来打造拦截器这个“引擎”。拦截器需要实现MyBatis的Interceptor接口，并在正确的时机插入我们的加解密逻辑。
3.1 加密拦截器：守护数据入库
加密拦截器（EncryptInterceptor）的目标是在SQL语句执行前，拦截设置参数的步骤，将明文替换为密文。它需要拦截ParameterHandler.setParameters方法。
import org.apache.ibatis.executor.parameter.ParameterHandler; import org.apache.ibatis.mapping.MappedStatement; import org.apache.ibatis.plugin.*; import org.springframework.stereotype.Component; import java.lang.reflect.Method; import java.sql.PreparedStatement; import java.util.*; /** * 加密拦截器。 * 拦截点：ParameterHandler.setParameters，在SQL执行前对参数进行加密。 */ @Intercepts({ @Signature(type = ParameterHandler.class, method = "setParameters", args = {PreparedStatement.class}) }) @Component public class EncryptInterceptor implements Interceptor { // 用于反射获取参数对象的方法名 private static final String GET_PARAMETER_OBJECT_METHOD = "getParameterObject"; @Override public Object intercept(Invocation invocation) throws Throwable { // 1. 获取被拦截的对象，确认是ParameterHandler Object target = invocation.getTarget(); if (!(target instanceof ParameterHandler)) { return invocation.proceed(); } ParameterHandler parameterHandler = (ParameterHandler) target; // 2. 通过反射获取当前要设置的参数对象 // MyBatis的ParameterHandler实现类（DefaultParameterHandler）有getParameterObject方法 Method getParamObjMethod = parameterHandler.getClass() .getDeclaredMethod(GET_PARAMETER_OBJECT_METHOD); getParamObjMethod.setAccessible(true); Object parameterObject = getParamObjMethod.invoke(parameterHandler); if (parameterObject != null) { // 3. 处理参数对象 processParameterObject(parameterObject); } // 4. 继续执行原始流程（此时参数对象的字段值已被加密） return invocation.proceed(); } /** * 处理参数对象，可能是一个实体，也可能是MyBatis的ParamMap。 */ private void processParameterObject(Object paramObj) throws IllegalAccessException { // 情况一：参数是MyBatis传入的ParamMap（常见于多参数方法，或使用@Param注解） if (paramObj instanceof Map) { // 遍历Map中的所有值，对每个是实体对象的值进行加密 // 使用IdentityHashMap或HashSet记录对象身份哈希，避免对同一个对象实例重复加密 Set<Integer> processedIdentityHashCodes = new HashSet<>(); Map<?, ?> paramMap = (Map<?, ?>) paramObj; for (Object value : paramMap.values()) { if (value != null && processedIdentityHashCodes.add(System.identityHashCode(value))) { EncryptDecryptUtils.encryptObject(value); } } } else { // 情况二：参数是单个实体对象 EncryptDecryptUtils.encryptObject(paramObj); } } @Override public Object plugin(Object target) { // 使用MyBatis提供的Plugin.wrap方法来创建代理对象 return Plugin.wrap(target, this); } // 如果需要，可以在这里设置拦截器属性，通常从Spring配置注入 // private Properties properties; // @Override // public void setProperties(Properties properties) { // this.properties = properties; // } }这个拦截器的关键点在于processParameterObject方法。它聪明地处理了MyBatis传递参数的两种主要方式：单个实体对象和包含多个参数的Map。对于Map，我们通过System.identityHashCode()来确保同一个对象实例只被加密一次，避免重复操作。
3.2 解密拦截器：还原数据出库
解密拦截器（DecryptInterceptor）的目标是在数据库结果集被转换成Java对象后、返回给调用者前，将密文字段还原为明文。它需要拦截ResultSetHandler.handleResultSets方法。
import org.apache.ibatis.executor.resultset.ResultSetHandler; import org.apache.ibatis.plugin.*; import org.springframework.core.annotation.AnnotationUtils; import org.springframework.stereotype.Component; import java.sql.Statement; import java.util.*; /** * 解密拦截器。 * 拦截点：ResultSetHandler.handleResultSets，在结果集映射为对象后对其进行解密。 */ @Intercepts({ @Signature(type = ResultSetHandler.class, method = "handleResultSets", args = {Statement.class}) }) @Component public class DecryptInterceptor implements Interceptor { @Override public Object intercept(Invocation invocation) throws Throwable { // 1. 执行原方法，获取数据库查询结果 Object result = invocation.proceed(); if (result == null) { return null; } // 2. 处理结果 decryptResult(result); // 3. 返回解密后的结果 return result; } /** * 对查询结果进行解密。 * 支持单个实体对象和集合（List）的递归处理。 */ @SuppressWarnings("unchecked") private void decryptResult(Object result) throws IllegalAccessException { if (result instanceof Collection) { // 处理查询列表的结果 Collection<Object> resultList = (Collection<Object>) result; for (Object item : resultList) { if (item != null && needToDecrypt(item)) { EncryptDecryptUtils.decryptObject(item); } } } else { // 处理查询单个对象的结果 if (needToDecrypt(result)) { EncryptDecryptUtils.decryptObject(result); } } } /** * 判断一个对象是否需要解密（即其类是否被@EncryptedTable注解标记）。 * 这是一个优化，避免对无关的实体类进行反射操作。 */ private boolean needToDecrypt(Object object) { Class<?> clazz = object.getClass(); EncryptedTable annotation = AnnotationUtils.findAnnotation(clazz, EncryptedTable.class); return annotation != null; } @Override public Object plugin(Object target) { return Plugin.wrap(target, this); } }解密拦截器的逻辑相对清晰：拿到查询结果后，判断结果是单个对象还是集合，然后遍历并调用工具类进行解密。needToDecrypt方法是一个简单的性能优化，先检查类级别的注解，如果连@EncryptedTable都没有，就无需进行后续的字段级反射操作。
4. 实战应用与进阶优化
现在，让我们把前面所有的零件组装起来，看看它们在实际项目中如何协同工作。同时，我也会分享几个让这套方案变得更健壮、更实用的进阶技巧。
4.1 完整使用示例
首先，定义一个需要加密的实体类，例如User：
import lombok.Data; @Data @EncryptedTable // 标记整个实体类需要加解密处理 public class User { private Long id; private String username; @EncryptedField // 标记此字段需要加密存储 private String mobilePhone; @EncryptedField // 标记此字段需要加密存储 private String idCardNumber; private String email; // 此字段不会被加密 }然后，在你的Mapper或Service中，像平常一样操作即可：
@Service public class UserService { @Autowired private UserMapper userMapper; public void createUser(User user) { // 插入时，拦截器会自动加密 mobilePhone 和 idCardNumber userMapper.insert(user); // 此时，数据库中的mobilePhone和idCardNumber字段已是密文 } public User getUserById(Long id) { // 查询时，拦截器会自动解密 mobilePhone 和 idCardNumber User user = userMapper.selectById(id); // 此时，user对象中的mobilePhone和idCardNumber字段已是明文 return user; } public void updatePhone(Long userId, String newPhone) { User user = new User(); user.setId(userId); user.setMobilePhone(newPhone); // 设置新手机号（明文） // 更新时，拦截器同样会自动加密这个字段 userMapper.updateById(user); } }对于MyBatis-Plus，你还需要确保拦截器被正确注册到Spring容器中。由于我们使用了@Component注解，并且MyBatis-Plus的自动配置通常会扫描Interceptor，它们应该能自动生效。如果遇到拦截器不生效的情况，可以检查一下MyBatis的配置：
# application.yml mybatis-plus: configuration: # 确保日志能打印出SQL，方便调试 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 如果你需要显式配置插件，可以在这里添加（通常自动注册即可） # global-config: # interceptor-list: # - com.yourpackage.interceptor.EncryptInterceptor # - com.yourpackage.interceptor.DecryptInterceptor4.2 关键进阶优化点
在实际使用中，你可能会遇到一些边缘情况或性能考量。这里有几个我踩过坑后总结的优化方向：
1. 类型处理的扩展性我们的工具类目前只处理了String和BigDecimal。现实项目中，你可能需要加密Integer类型的用户ID、LocalDate类型的生日，甚至是复杂的JSON对象。建议将类型处理逻辑抽象成策略模式。
// 定义一个加密处理器接口 public interface FieldEncryptor { boolean supports(Class<?> fieldType); Object encrypt(Object originalValue, String fieldName); Object decrypt(Object encryptedValue, String fieldName); } // 为String类型实现一个处理器 @Component public class StringAesEncryptor implements FieldEncryptor { @Override public boolean supports(Class<?> fieldType) { return String.class.equals(fieldType); } @Override public Object encrypt(Object originalValue, String fieldName) { // ... AES加密逻辑 } @Override public Object decrypt(Object encryptedValue, String fieldName) { // ... AES解密逻辑 } } // 在EncryptDecryptUtils中，注入一个List<FieldEncryptor>，遍历找到支持的处理器来执行加解密。2. 条件加密与密钥轮转不是所有场景都需要加密。你可以为@EncryptedField注解增加属性，比如boolean enabled()或String algorithm()，来实现条件加密或选择不同算法。更高级的场景是密钥轮转，即定期更换加密密钥。这需要在解密时能够识别数据是用哪一版密钥加密的（通常可以在密文中添加版本头或元数据），并选择对应的密钥进行解密。
3. 性能考量与开关控制反射操作有一定开销。如果实体类字段很多，但只有少数几个需要加密，needToDecrypt的类级别检查能过滤掉大部分无关对象。此外，强烈建议为整个加解密功能提供一个全局开关，例如通过@ConfigurationProperties读取一个配置项data.encryption.enabled。在工具类和拦截器中，先检查这个开关，如果为false则直接跳过所有加解密逻辑。这在开发、测试环境，或者需要临时排查问题时非常有用。
4. 与MyBatis-Plus的Lambda查询兼容性如果你在Service层使用MyBatis-Plus的LambdaQueryWrapper，例如queryWrapper.eq(User::getMobilePhone, “13800138000”)，这里传入的查询条件是明文。我们的加密拦截器目前只拦截了ParameterHandler，处理的是最终设置到PreparedStatement的参数对象。对于QueryWrapper中的条件值，它们通常会被MyBatis-Plus转换为SQL语句的一部分。要让条件值也自动加密，需要更深入地介入MyBatis-Plus的SQL解析过程，或者更简单一点：在构建Wrapper时，手动调用加密工具对条件值进行加密。
public User getUserByEncryptedPhone(String plainPhone) { String encryptedPhone = EncryptDecryptUtils.encryptString(plainPhone); // 需要一个直接加密字符串的方法 QueryWrapper<User> wrapper = new QueryWrapper<>(); wrapper.eq("mobile_phone", encryptedPhone); // 这里直接使用密文查询 return userMapper.selectOne(wrapper); }这种方式要求你知道查询条件对应的是加密字段，并且手动处理。对于更自动化的方案，可以考虑自定义一个LambdaQueryWrapper的子类，重写其eq等方法，在内部判断字段是否被@EncryptedField注解，如果是，则自动加密传入的值。这实现起来更复杂，但能提供更好的开发体验。
5. 数据库索引与模糊查询的挑战这是一个无法回避的痛点。一旦对字段加密，原本在明文上建立的数据库索引将失效，因为索引是基于密文存储的。同时，LIKE这样的模糊查询也变得不可能，因为密文数据的微小变化会导致明文完全无法预测。对于需要模糊查询或高效等值查询的字段（如手机号前缀查询），常见的折中方案是：
- 保留明文哈希：额外存储一个字段，如
phone_hash = SHA256(明文手机号)，用于等值查询和建立索引。但无法支持模糊查询。 - 可搜索加密：研究同态加密或确定性加密等高级密码学方案，但这会引入极大的复杂性和性能损耗。
- 业务设计调整：从根本上思考，是否真的需要对这些敏感字段进行频繁的模糊查询？能否通过其他非敏感字段（如用户ID、昵称）来定位数据？
最后，别忘了为你的加解密组件编写全面的单元测试和集成测试，覆盖各种数据类型、空值、集合查询、嵌套对象等场景。数据安全无小事，每一行处理敏感数据的代码都值得被慎重对待。这套基于MyBatis-Plus拦截器的方案，提供了一个平衡了开发效率、安全性和灵活性的起点，你可以根据自己项目的具体情况进行裁剪和增强。
