1. 项目概述当“零代码”遇上敏感信息保护最近在做一个老项目的安全加固客户要求对所有数据库里的敏感字段比如手机号、身份证号进行加密存储。一听到这个需求团队里几个兄弟脸都绿了。为啥这项目代码量几十万行业务逻辑盘根错节涉及敏感信息的字段散落在上百个实体类里。如果按照传统思路我们得一个个找到这些字段把String类型改成byte[]或者专门的对象然后在每个DAO层的增删改查方法里手动调用加解密工具类。这工作量没两个月根本下不来还极容易漏改、改错引入一堆隐蔽的Bug。就在大家准备“硬刚”的时候我突然想起之前研究MyBatis插件机制时的一个灵感能不能在数据进出数据库的这个“关口”做文章自动完成加解密而对业务代码完全透明呢这个想法就是今天要聊的核心——不改一行Java业务代码实现敏感信息的自动加解密。听起来有点“黑魔法”但原理其实很清晰就是利用MyBatis的TypeHandler类型处理器和Interceptor拦截器这两个扩展点在数据持久化的“最后一公里”和“最初一公里”进行拦截和转换。这不仅仅是偷懒。在微服务架构和领域驱动设计DDD流行的今天我们越来越强调业务逻辑的纯粹性。加解密本质上是一种与具体技术实现比如用了SM4还是AES强相关的“基础设施层”或“防腐层”的职责它不应该污染核心的业务领域模型。让业务代码保持干净只关心“用户手机号”这个业务概念而不必知道它存储时是密文这才是更优雅的架构。接下来我就把这个方案的完整设计思路、核心实现细节、避坑指南以及如何适配不同加密算法毫无保留地分享出来。2. 核心设计思路在数据流转的隘口布防要实现“零侵入”的加解密关键在于找准那个对数据有完全控制权又对业务代码无感的环节。在基于MyBatis的Java Web项目中这个环节就是SQL执行前后。我们的目标是当业务代码调用Mapper.insert(user)时user对象里的手机号是明文但在MyBatis生成INSERT语句并设置参数时自动将其转换为密文。反之当执行Mapper.selectById(1)查询时数据库返回的密文数据在MyBatis组装成User对象返回给业务层之前自动解密为明文。2.1 方案选型为什么是TypeHandler Interceptor市面上有一些方案比如在Getter/Setter里加注解并通过AOP处理或者在数据库连接池层面做代理。但经过对比TypeHandlerInterceptor的组合最为稳妥和通用。基于AOP注解的方案需要在实体类的字段或方法上标注Encrypt等注解通过Spring AOP或字节码增强在运行时处理。这确实能保持DAO接口的纯洁但仍然需要修改实体类违反了“不改一行代码”的初衷。而且AOP的切入点如果设置不当可能会影响性能或产生意想不到的副作用比如在序列化为JSON时也被拦截加密。数据库代理或驱动层方案比如修改JDBC驱动或使用中间件代理如ShardingSphere的加密功能。这个方案非常彻底对应用完全透明。但它的问题在于复杂度高、定制不灵活。你需要维护一个独立的代理服务或者深入研究JDBC驱动源码对大多数团队来说成本太高。而且它通常针对整个数据源生效难以实现基于字段粒度的、不同算法的加密。MyBatis TypeHandler Interceptor方案这正是我们采用的方案。它的优势非常明显无侵入性实体类、Mapper接口、XML文件都无需任何改动。业务开发者甚至感知不到加密的存在。精准控制可以通过配置精确指定哪些字段、哪些表需要加密并使用不同的加密算法。成熟稳定基于MyBatis官方提供的扩展机制兼容性好不会影响MyBatis的其他功能如缓存、插件等。职责清晰将加解密的逻辑收拢在数据持久化框架层符合分层架构思想。简单来说TypeHandler负责在Java类型和JDBC类型之间做转换它完美契合了“明文进密文出数据库密文进明文出数据库”这个需求。而Interceptor则为我们提供了更强大的能力比如在SQL执行前动态地识别哪些参数需要加密或者在多租户场景下根据上下文选择不同的加密密钥。2.2 核心挑战与应对策略理想很丰满但实现路上有几个必须跨过的坎挑战一如何识别需要加密的字段我们不能一股脑把所有String字段都加密。解决方案是建立一个加密字段注册表。可以通过配置文件如YAML、注解扫描虽然不改业务代码但我们可以有独立的配置类或者约定优于配置如字段名包含phone、id_card等的方式来实现。在TypeHandler或Interceptor中查询这个注册表决定是否进行加解密操作。挑战二加密后查询怎么办这是最棘手的问题。手机号加密后存入数据库WHERE phone ‘13800138000’这样的查询就会失效。解决方案是引入等值查询支持。对于需要等值查询的字段如手机号、邮箱必须使用支持等值查询的加密算法例如确定性加密相同的明文永远加密成相同的密文。但这会泄露频率信息安全性较低。格式保留加密FPE加密后的密文仍保持明文的格式如数字、字母。算法复杂实现难度高。盲索引Blind Index在数据库中额外存储一个明文的哈希值如加盐的SHA256作为索引列。查询时先计算查询条件的哈希值再用这个哈希值去匹配索引列。这是目前平衡安全与查询效率的常用方案但需要修改表结构增加索引列。 在我们的方案中通常建议对需要等值查询的敏感信息采用“盲索引”方案但这确实需要一定的数据库变更。如果业务上完全不需要通过密文字段进行查询则问题不存在。挑战三密钥管理。密钥绝不能硬编码在代码中。必须使用专业的密钥管理服务KMS如HashiCorp Vault、阿里云KMS或者至少在启动时从环境变量、配置中心注入。TypeHandler中应只持有密钥的引用或通过KMS客户端动态获取。理清了思路和挑战接下来我们就进入实战环节看看如何一步步实现这个“魔术”。3. 核心实现打造自动加解密的TypeHandler我们以最常用的国密算法SM4为例实现一个通用的加密TypeHandler。选择SM4是因为它在很多对安全性要求较高的国内项目中是标配并且是分组算法适合对固定长度的字段如身份证号进行加密。3.1 基础工具类SM4加解密首先我们需要一个可靠的SM4加解密工具。这里使用BouncyCastle提供商来支持国密算法。import org.bouncycastle.jce.provider.BouncyCastleProvider; import javax.crypto.Cipher; import javax.crypto.KeyGenerator; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import java.security.Security; import java.util.Base64; public class Sm4Util { static { // 注册BouncyCastle提供商 Security.addProvider(new BouncyCastleProvider()); } private static final String ALGORITHM_NAME SM4; private static final String TRANSFORMATION SM4/ECB/PKCS5Padding; // 使用ECB模式简单示例。生产环境应用CBC等模式并管理IV。 /** * 生成SM4密钥Base64编码 */ public static String generateKey() throws Exception { KeyGenerator kg KeyGenerator.getInstance(ALGORITHM_NAME, BC); kg.init(128); // SM4密钥长度固定为128位 SecretKey secretKey kg.generateKey(); return Base64.getEncoder().encodeToString(secretKey.getEncoded()); } /** * 加密 * param data 明文 * param keyBase64 Base64编码的密钥 * return Base64编码的密文 */ public static String encrypt(String data, String keyBase64) throws Exception { byte[] keyBytes Base64.getDecoder().decode(keyBase64); SecretKeySpec secretKeySpec new SecretKeySpec(keyBytes, ALGORITHM_NAME); Cipher cipher Cipher.getInstance(TRANSFORMATION, BC); cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec); byte[] encryptedBytes cipher.doFinal(data.getBytes(UTF-8)); return Base64.getEncoder().encodeToString(encryptedBytes); } /** * 解密 * param cipherTextBase64 Base64编码的密文 * param keyBase64 Base64编码的密钥 * return 明文 */ public static String decrypt(String cipherTextBase64, String keyBase64) throws Exception { byte[] keyBytes Base64.getDecoder().decode(keyBase64); SecretKeySpec secretKeySpec new SecretKeySpec(keyBytes, ALGORITHM_NAME); Cipher cipher Cipher.getInstance(TRANSFORMATION, BC); cipher.init(Cipher.DECRYPT_MODE, secretKeySpec); byte[] encryptedBytes Base64.getDecoder().decode(cipherTextBase64); byte[] decryptedBytes cipher.doFinal(encryptedBytes); return new String(decryptedBytes, UTF-8); } }注意上述示例为了简洁使用了ECB模式。在生产环境中绝对不要使用ECB模式对于分组加密模式应使用CBC、CTR或GCM等模式并妥善管理初始化向量IV。IV应当随机生成并和密文一起存储或传输。这里仅作原理演示。3.2 核心可插拔的加密TypeHandler接下来是重头戏——自定义TypeHandler。它需要继承MyBatis的BaseTypeHandler类并泛型化为String。import org.apache.ibatis.type.BaseTypeHandler; import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.MappedJdbcTypes; import org.apache.ibatis.type.MappedTypes; import java.sql.CallableStatement; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; // 声明此处理器处理JDBC的VARCHAR类型 MappedJdbcTypes(JdbcType.VARCHAR) // 声明此处理器处理Java的String类型 MappedTypes(String.class) public class EncryptTypeHandler extends BaseTypeHandlerString { // 这里注入加密服务或密钥。实际项目中应从Spring容器注入或从配置读取。 private final EncryptService encryptService; public EncryptTypeHandler(EncryptService encryptService) { this.encryptService encryptService; } // 也可以提供一个默认构造器用于MyBatis初始化但需要通过其他方式获取EncryptService如静态方法、ThreadLocal等不推荐。 // public EncryptTypeHandler() { // this.encryptService ApplicationContextHolder.getBean(EncryptService.class); // } Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { // 当MyBatis向PreparedStatement设置参数时调用 // 判断该字段是否需要加密根据字段名、Mapper方法等信息这里简化处理 if (shouldEncrypt(/* 如何获取字段名这是一个难点 */)) { String encryptedText encryptService.encrypt(parameter); ps.setString(i, encryptedText); } else { ps.setString(i, parameter); } } Override public String getNullableResult(ResultSet rs, String columnName) throws SQLException { // 从ResultSet根据列名获取值时调用 String dbValue rs.getString(columnName); return decryptIfNeeded(dbValue, columnName); } Override public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException { String dbValue rs.getString(columnIndex); // 通过columnIndex难以判断字段名通常优先使用columnName重载的方法 return decryptIfNeeded(dbValue, null); } Override public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { String dbValue cs.getString(columnIndex); return decryptIfNeeded(dbValue, null); } private boolean shouldEncrypt(/* 字段标识 */) { // 实现你的加密判断逻辑 // 例如查询一个“加密字段配置表”或根据线程上下文传递的元信息判断 return encryptService ! null encryptService.shouldEncrypt(/* 字段标识 */); } private String decryptIfNeeded(String dbValue, String columnName) { if (dbValue null) { return null; } // 判断该列值是否需要解密 if (shouldDecrypt(columnName)) { try { return encryptService.decrypt(dbValue); } catch (Exception e) { // 解密失败可能是非加密数据或密钥错误 // 记录日志并根据策略返回原值或抛出异常 // 例如return dbValue; // 宽容策略防止旧数据无法读取 throw new RuntimeException(Decrypt failed for column: columnName, e); } } return dbValue; } private boolean shouldDecrypt(String columnName) { // 实现你的解密判断逻辑通常与shouldEncrypt逻辑对应 // 一个简单的启发式规则如果值看起来像Base64编码的密文长度、字符集且该列在加密配置中则尝试解密 return encryptService ! null encryptService.shouldDecrypt(columnName); } }上面的代码留下了最关键的问题在setNonNullParameter方法里我们如何知道当前正在设置的是哪个字段MyBatis原生的TypeHandler并不提供这个上下文信息。这就需要我们请出第二位“帮手”——Interceptor。4. 进阶实现通过Interceptor传递加密上下文MyBatis的Interceptor可以拦截Executor的方法执行我们可以在SQL执行前拦截参数设置的过程并将需要加密的字段信息比如字段名、Mapper方法等通过ThreadLocal传递给我们自定义的TypeHandler。4.1 定义加密上下文与拦截器// 加密上下文用于在拦截器和TypeHandler之间传递信息 public class EncryptContext { private static final ThreadLocalSetString ENCRYPT_FIELD_NAMES new ThreadLocal(); public static void setEncryptFieldNames(SetString fieldNames) { ENCRYPT_FIELD_NAMES.set(fieldNames); } public static SetString getEncryptFieldNames() { return ENCRYPT_FIELD_NAMES.get(); } public static void clear() { ENCRYPT_FIELD_NAMES.remove(); } } // 加密拦截器 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 EncryptInterceptor implements Interceptor { private final EncryptService encryptService; private final EncryptFieldRegistry fieldRegistry; // 加密字段注册表 Override public Object intercept(Invocation invocation) throws Throwable { MappedStatement ms (MappedStatement) invocation.getArgs()[0]; Object parameter invocation.getArgs()[1]; // 1. 判断当前执行的Mapper方法是否需要加密处理 String mapperMethodId ms.getId(); // 例如com.example.mapper.UserMapper.insert if (!fieldRegistry.requiresEncryption(mapperMethodId)) { return invocation.proceed(); // 不需要加密直接放行 } // 2. 解析参数对象找出需要加密的字段名 // 这里需要根据你的参数类型Map、实体对象、多个参数Param进行解析 SetString fieldsToEncrypt parseEncryptFields(parameter, mapperMethodId); try { // 3. 将需要加密的字段名设置到线程上下文中 EncryptContext.setEncryptFieldNames(fieldsToEncrypt); // 4. 继续执行SQL return invocation.proceed(); } finally { // 5. 务必清理线程上下文防止内存泄漏和上下文污染 EncryptContext.clear(); } } private SetString parseEncryptFields(Object parameter, String mapperMethodId) { SetString fields new HashSet(); // 解析逻辑示例 // - 如果parameter是Map检查key是否在fieldRegistry中注册为需要加密 // - 如果parameter是实体对象通过反射获取其字段名并与fieldRegistry匹配 // - 可以从fieldRegistry根据mapperMethodId获取预定义的加密字段列表 // 具体实现取决于你的项目结构和配置方式 fields.add(phone); // 示例 fields.add(idCard); return fields; } Override public Object plugin(Object target) { return Plugin.wrap(target, this); } Override public void setProperties(Properties properties) { // 可以从mybatis配置中读取属性 } }4.2 改造TypeHandler利用上下文现在我们修改EncryptTypeHandler让它可以从EncryptContext中获取当前需要加密的字段信息。public class EncryptTypeHandler extends BaseTypeHandlerString { // ... 其他代码同上 ... Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { // 关键如何关联参数索引i与具体的字段名 // 在MyBatis中一个JavaBean参数被转换为多个PreparedStatement参数时其顺序与XML中#{}出现的顺序或Param顺序有关。 // 单纯通过索引i无法确定字段名。这是一个更复杂的问题。 // 方案A较复杂在Interceptor中不仅记录字段名还记录字段名到参数索引的映射关系。 // 方案B较实用放弃在TypeHandler中做加密判断将所有String类型字段都交给一个“智能”TypeHandler // 该Handler内部调用EncryptService由Service根据全局配置或上下文决定是否加密。 // 这里采用方案B的简化思路 String processedValue parameter; // 获取当前线程的加密上下文如果有 SetString encryptFields EncryptContext.getEncryptFieldNames(); // 注意我们仍然无法通过i知道当前是哪个字段。因此这个方案要求我们改变设计 // 要么在Interceptor层面就完成参数的加密替换要么使用更高级的MyBatis插件如ParameterHandler插件。 // 更可行的方案实现一个ParameterHandler拦截器 } }看到这里你会发现单纯靠TypeHandler无法完美解决字段识别问题。因此一个更成熟、更彻底的做法是实现一个ParameterHandler拦截器在TypeHandler执行之前直接修改参数对象。4.3 终极方案ParameterHandler拦截器ParameterHandler是MyBatis中负责设置SQL参数的核心接口。拦截它可以直接操作最终的参数值。Intercepts({ Signature(type ParameterHandler.class, method setParameters, args {PreparedStatement.class}) }) public class ParameterEncryptInterceptor implements Interceptor { private final EncryptService encryptService; private final EncryptFieldRegistry fieldRegistry; Override public Object intercept(Invocation invocation) throws Throwable { ParameterHandler parameterHandler (ParameterHandler) invocation.getTarget(); PreparedStatement ps (PreparedStatement) invocation.getArgs()[0]; // 通过反射获取MappedStatement和BoundSql进而获取参数对象和参数映射 // 这里需要深入MyBatis内部API代码较为复杂以下为概念性代码 /* Field mappedStatementField parameterHandler.getClass().getDeclaredField(mappedStatement); mappedStatementField.setAccessible(true); MappedStatement mappedStatement (MappedStatement) mappedStatementField.get(parameterHandler); Field boundSqlField parameterHandler.getClass().getDeclaredField(boundSql); boundSqlField.setAccessible(true); BoundSql boundSql (BoundSql) boundSqlField.get(parameterHandler); Object parameterObject boundSql.getParameterObject(); // 解析parameterObject找到需要加密的字段及其值 MapString, Object encryptedParams encryptService.encryptParameters(parameterObject, mappedStatement); // 获取原始的ParameterMetaData遍历并重新设置参数 // 将加密后的值替换进去 */ // 由于涉及大量反射和MyBatis内部状态处理稳定性风险较高。 // 因此许多团队会选择使用更上层的方案例如 // 1. 使用MyBatis-Plus等增强框架提供的字段加密插件如果满足需求。 // 2. 在Service层或DAO层使用AOP进行加解密侵入性稍高但更可控。 // 3. 使用ShardingSphere等中间件的数据加密功能对应用无侵入但运维复杂。 // 此处不展开复杂实现而是给出一个更工程化的建议 return invocation.proceed(); } }实操心得经过多次尝试我发现追求“绝对零侵入”的MyBatis插件实现其复杂度和稳定性风险往往高于收益。一个更务实、更易维护的折中方案是保留TypeHandler用于自动解密查询结果。这非常稳定因为查询结果列名是明确的。对于插入/更新时的加密采用轻量级侵入方式在实体类上使用自定义注解如EncryptedField并通过一个简单的BeanPostProcessor或工具类在数据进入MyBatis之前例如在Service层调用Mapper之前利用反射扫描注解并完成加密。这样业务代码只需要加一个注解DAO层代码依然干净且实现简单可控。这个“八二原则”方案——80%的便利自动解密用简单稳定的方式实现20%的妥协注解换取更低的复杂度在实际项目中更容易落地和推广。5. 配置与集成让一切运转起来无论采用哪种实现方案最终都需要在MyBatis配置中启用我们的组件。5.1 配置加密字段注册表我们可以用一个简单的配置类来定义哪些字段需要加密。# application.yml encrypt: fields: - table: user columns: [phone, id_card, email] algorithm: SM4 key-id: key-sm4-01 # 指向KMS中的密钥ID - table: order columns: [receiver_mobile] algorithm: AES key-id: key-aes-01对应的Java配置类Data ConfigurationProperties(prefix encrypt) public class EncryptProperties { private ListEncryptFieldConfig fields; } Data public class EncryptFieldConfig { private String table; private SetString columns; private String algorithm; private String keyId; } Component public class EncryptFieldRegistry { private final MapString, EncryptFieldConfig configMap new ConcurrentHashMap(); public EncryptFieldRegistry(EncryptProperties properties) { for (EncryptFieldConfig config : properties.getFields()) { for (String column : config.getColumns()) { // 生成key例如 user.phone String key config.getTable().toLowerCase() . column.toLowerCase(); configMap.put(key, config); } } } public boolean requiresEncryption(String table, String column) { return configMap.containsKey(table.toLowerCase() . column.toLowerCase()); } public EncryptFieldConfig getConfig(String table, String column) { return configMap.get(table.toLowerCase() . column.toLowerCase()); } }5.2 配置MyBatis使用自定义TypeHandler在MyBatis的配置文件中mybatis-config.xml或通过MyBatis-Spring的配置类注册我们的TypeHandler。Configuration public class MyBatisConfig { Bean public EncryptTypeHandler encryptTypeHandler(EncryptService encryptService) { return new EncryptTypeHandler(encryptService); } // 如果你使用了上面的折中方案仅用TypeHandler解密可以这样全局注册String类型的处理器 // 注意这会将所有String类型的JDBC参数和结果都交给这个处理器需要在处理器内部做好判断。 Bean public ConfigurationCustomizer mybatisConfigurationCustomizer(EncryptTypeHandler encryptTypeHandler) { return configuration - { TypeHandlerRegistry typeHandlerRegistry configuration.getTypeHandlerRegistry(); // 谨慎操作这可能会覆盖MyBatis默认的StringTypeHandler // 更好的做法是在mapper.xml的resultMap或具体字段上通过typeHandler属性指定 // typeHandlerRegistry.register(String.class, JdbcType.VARCHAR, encryptTypeHandler); }; } }更推荐的方式是在Mapper.xml的resultMap中针对特定字段指定typeHandlerresultMap idUserResultMap typeUser id propertyid columnid/ result propertyusername columnusername/ !-- 指定phone字段使用我们的加密处理器 -- result propertyphone columnphone typeHandlercom.example.handler.EncryptTypeHandler/ result propertyidCard columnid_card typeHandlercom.example.handler.EncryptTypeHandler/ /resultMap对于插入和更新如果采用“注解工具类”的加密方案则无需在XML中配置。5.3 密钥管理服务EncryptService实现EncryptService是加解密的门面负责算法选择、密钥获取和实际加解密操作。public interface EncryptService { String encrypt(String plainText, String table, String column); String decrypt(String cipherText, String table, String column); boolean shouldEncrypt(String table, String column); boolean shouldDecrypt(String table, String column); } Service public class EncryptServiceImpl implements EncryptService { private final EncryptFieldRegistry registry; private final KmsService kmsService; // 假设的KMS客户端 Override public String encrypt(String plainText, String table, String column) { if (StringUtils.isEmpty(plainText)) { return plainText; } EncryptFieldConfig config registry.getConfig(table, column); if (config null) { return plainText; } String key kmsService.getKey(config.getKeyId()); // 从KMS获取密钥 switch (config.getAlgorithm().toUpperCase()) { case SM4: return Sm4Util.encrypt(plainText, key); case AES: return AesUtil.encrypt(plainText, key); // ... 其他算法 default: throw new UnsupportedOperationException(Unsupported algorithm: config.getAlgorithm()); } } Override public String decrypt(String cipherText, String table, String column) { // 实现逻辑与encrypt类似反向操作 // 注意需要增加判断如果cipherText不是预期的密文格式如Base64应直接返回原值防止误解密非加密数据 } Override public boolean shouldEncrypt(String table, String column) { return registry.requiresEncryption(table, column); } Override public boolean shouldDecrypt(String table, String column) { // 解密判断可以更宽松一些例如尝试解密如果失败则返回原值 // 或者根据字段配置决定 return registry.requiresEncryption(table, column); } }6. 常见问题、排查技巧与进阶优化在实际落地过程中你会遇到各种各样的问题。下面是我踩过坑后总结的一些经验和解决方案。6.1 典型问题排查表问题现象可能原因排查步骤与解决方案查询结果部分字段为null或乱码1.TypeHandler解密失败但未正确处理异常导致返回null。2. 数据库存储的密文被破坏或编码不一致如UTF-8与GBK。3. 字段长度不足密文被截断。1. 在TypeHandler的decryptIfNeeded方法中添加详细日志打印列名、原始值、解密异常。2. 检查数据库连接字符串的字符集配置确保与加解密时的字符集一致推荐统一使用UTF-8。3.非常重要加密后数据长度会膨胀如经过Base64。必须修改数据库字段长度VARCHAR(11)的手机号字段可能需改为VARCHAR(64)或使用TEXT类型。插入/更新时报错数据过长数据库字段长度小于加密后字符串长度。同上修改表结构增加字段长度。建议预留足够空间例如按Base64编码后长度估算。加解密性能成为瓶颈1. 每次加解密都从远程KMS获取密钥。2. 算法模式选择不当如用了软件实现的RSA。3. 对大批量数据循环调用加解密。1. 在本地缓存密钥设置合理的过期时间。2. 对于大量数据使用对称加密如AES/SM4而非非对称加密RSA/SM2。3. 考虑在数据库层面进行加解密如MySQL的AES_ENCRYPT函数但这会将密钥暴露给DBA且移植性差。密文数据无法模糊查询或排序这是加密的本质决定的。如果业务需要模糊查询如姓名该字段不应加密。如果必须加密且要查询需采用“盲索引”或专门的密文搜索方案如可搜索加密但性能损耗大。务必在需求评审阶段与技术、产品明确查询需求。历史明文数据如何迁移上线时需要将存量明文数据加密。1.双写双读过渡期新代码同时写明文和密文到不同字段读优先读密文没有则读明文。同时运行一个离线任务将历史数据加密后更新到密文字段。2.停机迁移在低峰期停机用脚本批量加密所有历史数据。需要评估数据量和停机时间。6.2 进阶优化建议算法与模式选择国密推荐SM4对称、SM2非对称、SM3哈希。SM4的CBC或GCM模式是首选。国际算法AES-256-GCM是目前公认安全且高效的对称加密模式它同时提供了加密和完整性认证。避免DES、3DES、RC4、AES-ECB这些已不安全或不推荐的算法和模式。密钥生命周期管理定期轮转密钥需要定期更换。设计方案时需考虑密钥版本号新数据用新密钥加密旧数据在读取时根据版本号选择对应密钥解密。密钥分离不同环境开发、测试、生产、不同业务模块建议使用不同的密钥降低单点风险。监控与审计在EncryptService中增加监控点记录加解密操作的次数、成功率、耗时。对密钥的获取、使用进行审计日志记录满足合规要求。单元测试与集成测试必须为TypeHandler和EncryptService编写完善的单元测试覆盖正常加解密、空值处理、异常数据、密钥错误等场景。进行集成测试模拟从Controller到数据库的完整流程确保加解密对业务逻辑透明。6.3 一个更简单的起点使用MyBatis-Plus插件如果你的项目已经使用了MyBatis-Plus那么恭喜你事情简单了很多。MyBatis-Plus从3.4.0版本开始官方提供了字段加密插件其设计思想与我们上面的探讨类似但开箱即用稳定性更高。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加字段加密插件 interceptor.addInnerInterceptor(new FieldEncryptInterceptor()); return interceptor; } }你需要做的是实现一个IEncryptor接口并在实体字段上添加FieldEncrypt注解。Component public class Sm4Encryptor implements IEncryptor { Override public String encrypt(String plaintext, String key) { // 调用你的Sm4Util return Sm4Util.encrypt(plaintext, key); } Override public String decrypt(String ciphertext, String key) { return Sm4Util.decrypt(ciphertext, key); } } Data TableName(user) public class User { private Long id; private String username; FieldEncrypt(algorithm sm4, key your-key-id-in-config) private String phone; FieldEncrypt(algorithm sm4, key your-key-id-in-config) private String idCard; }这种方式虽然需要在实体类上加注解但完全免去了自己编写复杂插件的麻烦且MyBatis-Plus社区活跃遇到问题容易找到解决方案。这可以作为一个快速落地的选择。回过头看“不改一行Java代码”更像是一个理想的终极目标它指引我们追求更清晰的分层架构。但在工程实践中我们往往需要在“纯粹性”和“可行性”、“复杂性”之间做出权衡。无论是通过TypeHandler实现自动解密还是借助MyBatis-Plus的注解其核心价值都在于将技术细节加解密与业务逻辑分离。只要这个核心目标达到了即便需要增加几个注解项目的可维护性和安全性也已经得到了巨大的提升。最关键的是在方案设计之初就要和团队、产品一起把“哪些数据要加密”、“加密后怎么用”这些问题搞清楚这样才能选择最适合自己项目的“魔术”手法。
MyBatis TypeHandler与Interceptor实现数据库字段自动加解密方案
发布时间：2026/7/17 22:34:59
1. 项目概述当“零代码”遇上敏感信息保护最近在做一个老项目的安全加固客户要求对所有数据库里的敏感字段比如手机号、身份证号进行加密存储。一听到这个需求团队里几个兄弟脸都绿了。为啥这项目代码量几十万行业务逻辑盘根错节涉及敏感信息的字段散落在上百个实体类里。如果按照传统思路我们得一个个找到这些字段把String类型改成byte[]或者专门的对象然后在每个DAO层的增删改查方法里手动调用加解密工具类。这工作量没两个月根本下不来还极容易漏改、改错引入一堆隐蔽的Bug。就在大家准备“硬刚”的时候我突然想起之前研究MyBatis插件机制时的一个灵感能不能在数据进出数据库的这个“关口”做文章自动完成加解密而对业务代码完全透明呢这个想法就是今天要聊的核心——不改一行Java业务代码实现敏感信息的自动加解密。听起来有点“黑魔法”但原理其实很清晰就是利用MyBatis的TypeHandler类型处理器和Interceptor拦截器这两个扩展点在数据持久化的“最后一公里”和“最初一公里”进行拦截和转换。这不仅仅是偷懒。在微服务架构和领域驱动设计DDD流行的今天我们越来越强调业务逻辑的纯粹性。加解密本质上是一种与具体技术实现比如用了SM4还是AES强相关的“基础设施层”或“防腐层”的职责它不应该污染核心的业务领域模型。让业务代码保持干净只关心“用户手机号”这个业务概念而不必知道它存储时是密文这才是更优雅的架构。接下来我就把这个方案的完整设计思路、核心实现细节、避坑指南以及如何适配不同加密算法毫无保留地分享出来。2. 核心设计思路在数据流转的隘口布防要实现“零侵入”的加解密关键在于找准那个对数据有完全控制权又对业务代码无感的环节。在基于MyBatis的Java Web项目中这个环节就是SQL执行前后。我们的目标是当业务代码调用Mapper.insert(user)时user对象里的手机号是明文但在MyBatis生成INSERT语句并设置参数时自动将其转换为密文。反之当执行Mapper.selectById(1)查询时数据库返回的密文数据在MyBatis组装成User对象返回给业务层之前自动解密为明文。2.1 方案选型为什么是TypeHandler Interceptor市面上有一些方案比如在Getter/Setter里加注解并通过AOP处理或者在数据库连接池层面做代理。但经过对比TypeHandlerInterceptor的组合最为稳妥和通用。基于AOP注解的方案需要在实体类的字段或方法上标注Encrypt等注解通过Spring AOP或字节码增强在运行时处理。这确实能保持DAO接口的纯洁但仍然需要修改实体类违反了“不改一行代码”的初衷。而且AOP的切入点如果设置不当可能会影响性能或产生意想不到的副作用比如在序列化为JSON时也被拦截加密。数据库代理或驱动层方案比如修改JDBC驱动或使用中间件代理如ShardingSphere的加密功能。这个方案非常彻底对应用完全透明。但它的问题在于复杂度高、定制不灵活。你需要维护一个独立的代理服务或者深入研究JDBC驱动源码对大多数团队来说成本太高。而且它通常针对整个数据源生效难以实现基于字段粒度的、不同算法的加密。MyBatis TypeHandler Interceptor方案这正是我们采用的方案。它的优势非常明显无侵入性实体类、Mapper接口、XML文件都无需任何改动。业务开发者甚至感知不到加密的存在。精准控制可以通过配置精确指定哪些字段、哪些表需要加密并使用不同的加密算法。成熟稳定基于MyBatis官方提供的扩展机制兼容性好不会影响MyBatis的其他功能如缓存、插件等。职责清晰将加解密的逻辑收拢在数据持久化框架层符合分层架构思想。简单来说TypeHandler负责在Java类型和JDBC类型之间做转换它完美契合了“明文进密文出数据库密文进明文出数据库”这个需求。而Interceptor则为我们提供了更强大的能力比如在SQL执行前动态地识别哪些参数需要加密或者在多租户场景下根据上下文选择不同的加密密钥。2.2 核心挑战与应对策略理想很丰满但实现路上有几个必须跨过的坎挑战一如何识别需要加密的字段我们不能一股脑把所有String字段都加密。解决方案是建立一个加密字段注册表。可以通过配置文件如YAML、注解扫描虽然不改业务代码但我们可以有独立的配置类或者约定优于配置如字段名包含phone、id_card等的方式来实现。在TypeHandler或Interceptor中查询这个注册表决定是否进行加解密操作。挑战二加密后查询怎么办这是最棘手的问题。手机号加密后存入数据库WHERE phone ‘13800138000’这样的查询就会失效。解决方案是引入等值查询支持。对于需要等值查询的字段如手机号、邮箱必须使用支持等值查询的加密算法例如确定性加密相同的明文永远加密成相同的密文。但这会泄露频率信息安全性较低。格式保留加密FPE加密后的密文仍保持明文的格式如数字、字母。算法复杂实现难度高。盲索引Blind Index在数据库中额外存储一个明文的哈希值如加盐的SHA256作为索引列。查询时先计算查询条件的哈希值再用这个哈希值去匹配索引列。这是目前平衡安全与查询效率的常用方案但需要修改表结构增加索引列。 在我们的方案中通常建议对需要等值查询的敏感信息采用“盲索引”方案但这确实需要一定的数据库变更。如果业务上完全不需要通过密文字段进行查询则问题不存在。挑战三密钥管理。密钥绝不能硬编码在代码中。必须使用专业的密钥管理服务KMS如HashiCorp Vault、阿里云KMS或者至少在启动时从环境变量、配置中心注入。TypeHandler中应只持有密钥的引用或通过KMS客户端动态获取。理清了思路和挑战接下来我们就进入实战环节看看如何一步步实现这个“魔术”。3. 核心实现打造自动加解密的TypeHandler我们以最常用的国密算法SM4为例实现一个通用的加密TypeHandler。选择SM4是因为它在很多对安全性要求较高的国内项目中是标配并且是分组算法适合对固定长度的字段如身份证号进行加密。3.1 基础工具类SM4加解密首先我们需要一个可靠的SM4加解密工具。这里使用BouncyCastle提供商来支持国密算法。import org.bouncycastle.jce.provider.BouncyCastleProvider; import javax.crypto.Cipher; import javax.crypto.KeyGenerator; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import java.security.Security; import java.util.Base64; public class Sm4Util { static { // 注册BouncyCastle提供商 Security.addProvider(new BouncyCastleProvider()); } private static final String ALGORITHM_NAME SM4; private static final String TRANSFORMATION SM4/ECB/PKCS5Padding; // 使用ECB模式简单示例。生产环境应用CBC等模式并管理IV。 /** * 生成SM4密钥Base64编码 */ public static String generateKey() throws Exception { KeyGenerator kg KeyGenerator.getInstance(ALGORITHM_NAME, BC); kg.init(128); // SM4密钥长度固定为128位 SecretKey secretKey kg.generateKey(); return Base64.getEncoder().encodeToString(secretKey.getEncoded()); } /** * 加密 * param data 明文 * param keyBase64 Base64编码的密钥 * return Base64编码的密文 */ public static String encrypt(String data, String keyBase64) throws Exception { byte[] keyBytes Base64.getDecoder().decode(keyBase64); SecretKeySpec secretKeySpec new SecretKeySpec(keyBytes, ALGORITHM_NAME); Cipher cipher Cipher.getInstance(TRANSFORMATION, BC); cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec); byte[] encryptedBytes cipher.doFinal(data.getBytes(UTF-8)); return Base64.getEncoder().encodeToString(encryptedBytes); } /** * 解密 * param cipherTextBase64 Base64编码的密文 * param keyBase64 Base64编码的密钥 * return 明文 */ public static String decrypt(String cipherTextBase64, String keyBase64) throws Exception { byte[] keyBytes Base64.getDecoder().decode(keyBase64); SecretKeySpec secretKeySpec new SecretKeySpec(keyBytes, ALGORITHM_NAME); Cipher cipher Cipher.getInstance(TRANSFORMATION, BC); cipher.init(Cipher.DECRYPT_MODE, secretKeySpec); byte[] encryptedBytes Base64.getDecoder().decode(cipherTextBase64); byte[] decryptedBytes cipher.doFinal(encryptedBytes); return new String(decryptedBytes, UTF-8); } }注意上述示例为了简洁使用了ECB模式。在生产环境中绝对不要使用ECB模式对于分组加密模式应使用CBC、CTR或GCM等模式并妥善管理初始化向量IV。IV应当随机生成并和密文一起存储或传输。这里仅作原理演示。3.2 核心可插拔的加密TypeHandler接下来是重头戏——自定义TypeHandler。它需要继承MyBatis的BaseTypeHandler类并泛型化为String。import org.apache.ibatis.type.BaseTypeHandler; import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.MappedJdbcTypes; import org.apache.ibatis.type.MappedTypes; import java.sql.CallableStatement; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; // 声明此处理器处理JDBC的VARCHAR类型 MappedJdbcTypes(JdbcType.VARCHAR) // 声明此处理器处理Java的String类型 MappedTypes(String.class) public class EncryptTypeHandler extends BaseTypeHandlerString { // 这里注入加密服务或密钥。实际项目中应从Spring容器注入或从配置读取。 private final EncryptService encryptService; public EncryptTypeHandler(EncryptService encryptService) { this.encryptService encryptService; } // 也可以提供一个默认构造器用于MyBatis初始化但需要通过其他方式获取EncryptService如静态方法、ThreadLocal等不推荐。 // public EncryptTypeHandler() { // this.encryptService ApplicationContextHolder.getBean(EncryptService.class); // } Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { // 当MyBatis向PreparedStatement设置参数时调用 // 判断该字段是否需要加密根据字段名、Mapper方法等信息这里简化处理 if (shouldEncrypt(/* 如何获取字段名这是一个难点 */)) { String encryptedText encryptService.encrypt(parameter); ps.setString(i, encryptedText); } else { ps.setString(i, parameter); } } Override public String getNullableResult(ResultSet rs, String columnName) throws SQLException { // 从ResultSet根据列名获取值时调用 String dbValue rs.getString(columnName); return decryptIfNeeded(dbValue, columnName); } Override public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException { String dbValue rs.getString(columnIndex); // 通过columnIndex难以判断字段名通常优先使用columnName重载的方法 return decryptIfNeeded(dbValue, null); } Override public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { String dbValue cs.getString(columnIndex); return decryptIfNeeded(dbValue, null); } private boolean shouldEncrypt(/* 字段标识 */) { // 实现你的加密判断逻辑 // 例如查询一个“加密字段配置表”或根据线程上下文传递的元信息判断 return encryptService ! null encryptService.shouldEncrypt(/* 字段标识 */); } private String decryptIfNeeded(String dbValue, String columnName) { if (dbValue null) { return null; } // 判断该列值是否需要解密 if (shouldDecrypt(columnName)) { try { return encryptService.decrypt(dbValue); } catch (Exception e) { // 解密失败可能是非加密数据或密钥错误 // 记录日志并根据策略返回原值或抛出异常 // 例如return dbValue; // 宽容策略防止旧数据无法读取 throw new RuntimeException(Decrypt failed for column: columnName, e); } } return dbValue; } private boolean shouldDecrypt(String columnName) { // 实现你的解密判断逻辑通常与shouldEncrypt逻辑对应 // 一个简单的启发式规则如果值看起来像Base64编码的密文长度、字符集且该列在加密配置中则尝试解密 return encryptService ! null encryptService.shouldDecrypt(columnName); } }上面的代码留下了最关键的问题在setNonNullParameter方法里我们如何知道当前正在设置的是哪个字段MyBatis原生的TypeHandler并不提供这个上下文信息。这就需要我们请出第二位“帮手”——Interceptor。4. 进阶实现通过Interceptor传递加密上下文MyBatis的Interceptor可以拦截Executor的方法执行我们可以在SQL执行前拦截参数设置的过程并将需要加密的字段信息比如字段名、Mapper方法等通过ThreadLocal传递给我们自定义的TypeHandler。4.1 定义加密上下文与拦截器// 加密上下文用于在拦截器和TypeHandler之间传递信息 public class EncryptContext { private static final ThreadLocalSetString ENCRYPT_FIELD_NAMES new ThreadLocal(); public static void setEncryptFieldNames(SetString fieldNames) { ENCRYPT_FIELD_NAMES.set(fieldNames); } public static SetString getEncryptFieldNames() { return ENCRYPT_FIELD_NAMES.get(); } public static void clear() { ENCRYPT_FIELD_NAMES.remove(); } } // 加密拦截器 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 EncryptInterceptor implements Interceptor { private final EncryptService encryptService; private final EncryptFieldRegistry fieldRegistry; // 加密字段注册表 Override public Object intercept(Invocation invocation) throws Throwable { MappedStatement ms (MappedStatement) invocation.getArgs()[0]; Object parameter invocation.getArgs()[1]; // 1. 判断当前执行的Mapper方法是否需要加密处理 String mapperMethodId ms.getId(); // 例如com.example.mapper.UserMapper.insert if (!fieldRegistry.requiresEncryption(mapperMethodId)) { return invocation.proceed(); // 不需要加密直接放行 } // 2. 解析参数对象找出需要加密的字段名 // 这里需要根据你的参数类型Map、实体对象、多个参数Param进行解析 SetString fieldsToEncrypt parseEncryptFields(parameter, mapperMethodId); try { // 3. 将需要加密的字段名设置到线程上下文中 EncryptContext.setEncryptFieldNames(fieldsToEncrypt); // 4. 继续执行SQL return invocation.proceed(); } finally { // 5. 务必清理线程上下文防止内存泄漏和上下文污染 EncryptContext.clear(); } } private SetString parseEncryptFields(Object parameter, String mapperMethodId) { SetString fields new HashSet(); // 解析逻辑示例 // - 如果parameter是Map检查key是否在fieldRegistry中注册为需要加密 // - 如果parameter是实体对象通过反射获取其字段名并与fieldRegistry匹配 // - 可以从fieldRegistry根据mapperMethodId获取预定义的加密字段列表 // 具体实现取决于你的项目结构和配置方式 fields.add(phone); // 示例 fields.add(idCard); return fields; } Override public Object plugin(Object target) { return Plugin.wrap(target, this); } Override public void setProperties(Properties properties) { // 可以从mybatis配置中读取属性 } }4.2 改造TypeHandler利用上下文现在我们修改EncryptTypeHandler让它可以从EncryptContext中获取当前需要加密的字段信息。public class EncryptTypeHandler extends BaseTypeHandlerString { // ... 其他代码同上 ... Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { // 关键如何关联参数索引i与具体的字段名 // 在MyBatis中一个JavaBean参数被转换为多个PreparedStatement参数时其顺序与XML中#{}出现的顺序或Param顺序有关。 // 单纯通过索引i无法确定字段名。这是一个更复杂的问题。 // 方案A较复杂在Interceptor中不仅记录字段名还记录字段名到参数索引的映射关系。 // 方案B较实用放弃在TypeHandler中做加密判断将所有String类型字段都交给一个“智能”TypeHandler // 该Handler内部调用EncryptService由Service根据全局配置或上下文决定是否加密。 // 这里采用方案B的简化思路 String processedValue parameter; // 获取当前线程的加密上下文如果有 SetString encryptFields EncryptContext.getEncryptFieldNames(); // 注意我们仍然无法通过i知道当前是哪个字段。因此这个方案要求我们改变设计 // 要么在Interceptor层面就完成参数的加密替换要么使用更高级的MyBatis插件如ParameterHandler插件。 // 更可行的方案实现一个ParameterHandler拦截器 } }看到这里你会发现单纯靠TypeHandler无法完美解决字段识别问题。因此一个更成熟、更彻底的做法是实现一个ParameterHandler拦截器在TypeHandler执行之前直接修改参数对象。4.3 终极方案ParameterHandler拦截器ParameterHandler是MyBatis中负责设置SQL参数的核心接口。拦截它可以直接操作最终的参数值。Intercepts({ Signature(type ParameterHandler.class, method setParameters, args {PreparedStatement.class}) }) public class ParameterEncryptInterceptor implements Interceptor { private final EncryptService encryptService; private final EncryptFieldRegistry fieldRegistry; Override public Object intercept(Invocation invocation) throws Throwable { ParameterHandler parameterHandler (ParameterHandler) invocation.getTarget(); PreparedStatement ps (PreparedStatement) invocation.getArgs()[0]; // 通过反射获取MappedStatement和BoundSql进而获取参数对象和参数映射 // 这里需要深入MyBatis内部API代码较为复杂以下为概念性代码 /* Field mappedStatementField parameterHandler.getClass().getDeclaredField(mappedStatement); mappedStatementField.setAccessible(true); MappedStatement mappedStatement (MappedStatement) mappedStatementField.get(parameterHandler); Field boundSqlField parameterHandler.getClass().getDeclaredField(boundSql); boundSqlField.setAccessible(true); BoundSql boundSql (BoundSql) boundSqlField.get(parameterHandler); Object parameterObject boundSql.getParameterObject(); // 解析parameterObject找到需要加密的字段及其值 MapString, Object encryptedParams encryptService.encryptParameters(parameterObject, mappedStatement); // 获取原始的ParameterMetaData遍历并重新设置参数 // 将加密后的值替换进去 */ // 由于涉及大量反射和MyBatis内部状态处理稳定性风险较高。 // 因此许多团队会选择使用更上层的方案例如 // 1. 使用MyBatis-Plus等增强框架提供的字段加密插件如果满足需求。 // 2. 在Service层或DAO层使用AOP进行加解密侵入性稍高但更可控。 // 3. 使用ShardingSphere等中间件的数据加密功能对应用无侵入但运维复杂。 // 此处不展开复杂实现而是给出一个更工程化的建议 return invocation.proceed(); } }实操心得经过多次尝试我发现追求“绝对零侵入”的MyBatis插件实现其复杂度和稳定性风险往往高于收益。一个更务实、更易维护的折中方案是保留TypeHandler用于自动解密查询结果。这非常稳定因为查询结果列名是明确的。对于插入/更新时的加密采用轻量级侵入方式在实体类上使用自定义注解如EncryptedField并通过一个简单的BeanPostProcessor或工具类在数据进入MyBatis之前例如在Service层调用Mapper之前利用反射扫描注解并完成加密。这样业务代码只需要加一个注解DAO层代码依然干净且实现简单可控。这个“八二原则”方案——80%的便利自动解密用简单稳定的方式实现20%的妥协注解换取更低的复杂度在实际项目中更容易落地和推广。5. 配置与集成让一切运转起来无论采用哪种实现方案最终都需要在MyBatis配置中启用我们的组件。5.1 配置加密字段注册表我们可以用一个简单的配置类来定义哪些字段需要加密。# application.yml encrypt: fields: - table: user columns: [phone, id_card, email] algorithm: SM4 key-id: key-sm4-01 # 指向KMS中的密钥ID - table: order columns: [receiver_mobile] algorithm: AES key-id: key-aes-01对应的Java配置类Data ConfigurationProperties(prefix encrypt) public class EncryptProperties { private ListEncryptFieldConfig fields; } Data public class EncryptFieldConfig { private String table; private SetString columns; private String algorithm; private String keyId; } Component public class EncryptFieldRegistry { private final MapString, EncryptFieldConfig configMap new ConcurrentHashMap(); public EncryptFieldRegistry(EncryptProperties properties) { for (EncryptFieldConfig config : properties.getFields()) { for (String column : config.getColumns()) { // 生成key例如 user.phone String key config.getTable().toLowerCase() . column.toLowerCase(); configMap.put(key, config); } } } public boolean requiresEncryption(String table, String column) { return configMap.containsKey(table.toLowerCase() . column.toLowerCase()); } public EncryptFieldConfig getConfig(String table, String column) { return configMap.get(table.toLowerCase() . column.toLowerCase()); } }5.2 配置MyBatis使用自定义TypeHandler在MyBatis的配置文件中mybatis-config.xml或通过MyBatis-Spring的配置类注册我们的TypeHandler。Configuration public class MyBatisConfig { Bean public EncryptTypeHandler encryptTypeHandler(EncryptService encryptService) { return new EncryptTypeHandler(encryptService); } // 如果你使用了上面的折中方案仅用TypeHandler解密可以这样全局注册String类型的处理器 // 注意这会将所有String类型的JDBC参数和结果都交给这个处理器需要在处理器内部做好判断。 Bean public ConfigurationCustomizer mybatisConfigurationCustomizer(EncryptTypeHandler encryptTypeHandler) { return configuration - { TypeHandlerRegistry typeHandlerRegistry configuration.getTypeHandlerRegistry(); // 谨慎操作这可能会覆盖MyBatis默认的StringTypeHandler // 更好的做法是在mapper.xml的resultMap或具体字段上通过typeHandler属性指定 // typeHandlerRegistry.register(String.class, JdbcType.VARCHAR, encryptTypeHandler); }; } }更推荐的方式是在Mapper.xml的resultMap中针对特定字段指定typeHandlerresultMap idUserResultMap typeUser id propertyid columnid/ result propertyusername columnusername/ !-- 指定phone字段使用我们的加密处理器 -- result propertyphone columnphone typeHandlercom.example.handler.EncryptTypeHandler/ result propertyidCard columnid_card typeHandlercom.example.handler.EncryptTypeHandler/ /resultMap对于插入和更新如果采用“注解工具类”的加密方案则无需在XML中配置。5.3 密钥管理服务EncryptService实现EncryptService是加解密的门面负责算法选择、密钥获取和实际加解密操作。public interface EncryptService { String encrypt(String plainText, String table, String column); String decrypt(String cipherText, String table, String column); boolean shouldEncrypt(String table, String column); boolean shouldDecrypt(String table, String column); } Service public class EncryptServiceImpl implements EncryptService { private final EncryptFieldRegistry registry; private final KmsService kmsService; // 假设的KMS客户端 Override public String encrypt(String plainText, String table, String column) { if (StringUtils.isEmpty(plainText)) { return plainText; } EncryptFieldConfig config registry.getConfig(table, column); if (config null) { return plainText; } String key kmsService.getKey(config.getKeyId()); // 从KMS获取密钥 switch (config.getAlgorithm().toUpperCase()) { case SM4: return Sm4Util.encrypt(plainText, key); case AES: return AesUtil.encrypt(plainText, key); // ... 其他算法 default: throw new UnsupportedOperationException(Unsupported algorithm: config.getAlgorithm()); } } Override public String decrypt(String cipherText, String table, String column) { // 实现逻辑与encrypt类似反向操作 // 注意需要增加判断如果cipherText不是预期的密文格式如Base64应直接返回原值防止误解密非加密数据 } Override public boolean shouldEncrypt(String table, String column) { return registry.requiresEncryption(table, column); } Override public boolean shouldDecrypt(String table, String column) { // 解密判断可以更宽松一些例如尝试解密如果失败则返回原值 // 或者根据字段配置决定 return registry.requiresEncryption(table, column); } }6. 常见问题、排查技巧与进阶优化在实际落地过程中你会遇到各种各样的问题。下面是我踩过坑后总结的一些经验和解决方案。6.1 典型问题排查表问题现象可能原因排查步骤与解决方案查询结果部分字段为null或乱码1.TypeHandler解密失败但未正确处理异常导致返回null。2. 数据库存储的密文被破坏或编码不一致如UTF-8与GBK。3. 字段长度不足密文被截断。1. 在TypeHandler的decryptIfNeeded方法中添加详细日志打印列名、原始值、解密异常。2. 检查数据库连接字符串的字符集配置确保与加解密时的字符集一致推荐统一使用UTF-8。3.非常重要加密后数据长度会膨胀如经过Base64。必须修改数据库字段长度VARCHAR(11)的手机号字段可能需改为VARCHAR(64)或使用TEXT类型。插入/更新时报错数据过长数据库字段长度小于加密后字符串长度。同上修改表结构增加字段长度。建议预留足够空间例如按Base64编码后长度估算。加解密性能成为瓶颈1. 每次加解密都从远程KMS获取密钥。2. 算法模式选择不当如用了软件实现的RSA。3. 对大批量数据循环调用加解密。1. 在本地缓存密钥设置合理的过期时间。2. 对于大量数据使用对称加密如AES/SM4而非非对称加密RSA/SM2。3. 考虑在数据库层面进行加解密如MySQL的AES_ENCRYPT函数但这会将密钥暴露给DBA且移植性差。密文数据无法模糊查询或排序这是加密的本质决定的。如果业务需要模糊查询如姓名该字段不应加密。如果必须加密且要查询需采用“盲索引”或专门的密文搜索方案如可搜索加密但性能损耗大。务必在需求评审阶段与技术、产品明确查询需求。历史明文数据如何迁移上线时需要将存量明文数据加密。1.双写双读过渡期新代码同时写明文和密文到不同字段读优先读密文没有则读明文。同时运行一个离线任务将历史数据加密后更新到密文字段。2.停机迁移在低峰期停机用脚本批量加密所有历史数据。需要评估数据量和停机时间。6.2 进阶优化建议算法与模式选择国密推荐SM4对称、SM2非对称、SM3哈希。SM4的CBC或GCM模式是首选。国际算法AES-256-GCM是目前公认安全且高效的对称加密模式它同时提供了加密和完整性认证。避免DES、3DES、RC4、AES-ECB这些已不安全或不推荐的算法和模式。密钥生命周期管理定期轮转密钥需要定期更换。设计方案时需考虑密钥版本号新数据用新密钥加密旧数据在读取时根据版本号选择对应密钥解密。密钥分离不同环境开发、测试、生产、不同业务模块建议使用不同的密钥降低单点风险。监控与审计在EncryptService中增加监控点记录加解密操作的次数、成功率、耗时。对密钥的获取、使用进行审计日志记录满足合规要求。单元测试与集成测试必须为TypeHandler和EncryptService编写完善的单元测试覆盖正常加解密、空值处理、异常数据、密钥错误等场景。进行集成测试模拟从Controller到数据库的完整流程确保加解密对业务逻辑透明。6.3 一个更简单的起点使用MyBatis-Plus插件如果你的项目已经使用了MyBatis-Plus那么恭喜你事情简单了很多。MyBatis-Plus从3.4.0版本开始官方提供了字段加密插件其设计思想与我们上面的探讨类似但开箱即用稳定性更高。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加字段加密插件 interceptor.addInnerInterceptor(new FieldEncryptInterceptor()); return interceptor; } }你需要做的是实现一个IEncryptor接口并在实体字段上添加FieldEncrypt注解。Component public class Sm4Encryptor implements IEncryptor { Override public String encrypt(String plaintext, String key) { // 调用你的Sm4Util return Sm4Util.encrypt(plaintext, key); } Override public String decrypt(String ciphertext, String key) { return Sm4Util.decrypt(ciphertext, key); } } Data TableName(user) public class User { private Long id; private String username; FieldEncrypt(algorithm sm4, key your-key-id-in-config) private String phone; FieldEncrypt(algorithm sm4, key your-key-id-in-config) private String idCard; }这种方式虽然需要在实体类上加注解但完全免去了自己编写复杂插件的麻烦且MyBatis-Plus社区活跃遇到问题容易找到解决方案。这可以作为一个快速落地的选择。回过头看“不改一行Java代码”更像是一个理想的终极目标它指引我们追求更清晰的分层架构。但在工程实践中我们往往需要在“纯粹性”和“可行性”、“复杂性”之间做出权衡。无论是通过TypeHandler实现自动解密还是借助MyBatis-Plus的注解其核心价值都在于将技术细节加解密与业务逻辑分离。只要这个核心目标达到了即便需要增加几个注解项目的可维护性和安全性也已经得到了巨大的提升。最关键的是在方案设计之初就要和团队、产品一起把“哪些数据要加密”、“加密后怎么用”这些问题搞清楚这样才能选择最适合自己项目的“魔术”手法。
