加密SDK的整体架构：四个核心模块的设计思路

做字段级加密SDK，说白了就是给应用里那些敏感字段加个「保险柜」。很多团队一上来就写AES加密函数，然后到处调用。嗯，这种做法我在早期项目里也干过，后来吃了大亏——密钥写死在代码里、缓存穿透把数据库打爆、配置改一次就要重新部署。所以这章咱们聊聊真正的架构该怎么搭。

我个人习惯把SDK拆成四个模块：加密引擎、密钥管理、缓存、配置。它们各司其职，但又不能彻底割裂。下面挨个说。

4.1 加密引擎：不只是算法调用

加密引擎是干活的主力。你想想看，它要处理的不只是「把明文变密文」这么简单。

我建议引擎层至少抽象出三层：

• 算法适配层：支持AES-GCM、SM4-GCM等国密算法，以及Chacha20等流式算法。不同字段可能要选不同算法——手机号用AES-GCM就够了，身份证号可能需要SM4。
• 模式控制层：决定是用确定性加密（Deterministic Encryption）还是随机加密。我做电商项目时，订单号需要等值查询，就必须用确定性模式；而地址字段用随机模式，每次加密结果不同，更安全。
• 性能兜底层：引擎内部要维护一个算法执行器池。Java里可以用线程池，Go里用goroutine池。避免每次加解密都创建新资源。

下面是引擎启动的简化伪代码：

// 引擎初始化流程
CryptoEngine engine = CryptoEngine.builder()
    .algorithm("AES/GCM/NoPadding")   // 先注册，不是直接实例化
    .keyProvider(myKeyManager)         // 注入密钥管理模块
    .enableCache(true)                 // 是否启用加密结果缓存
    .build();

// 调用示例
String cipher = engine.encrypt("13800138000", "PHONE");

4.2 密钥管理：命根子得管好

密钥是SDK的命根子。我记得有次线上事故，运维同事把密钥文件备份到公共存储桶里，结果被爬虫扫到了…

密钥管理模块要处理三个核心问题：

1. 密钥的生命周期：创建、激活、过期、轮换、销毁。每个字段可以绑定不同的密钥版本。比如「手机号」用版本2，「地址」用版本3，互不影响。
2. 密钥的存储方式：不能存数据库明文。我推荐用KMS（云服务）或本地HSM，退一步也要用Vault这类工具。SDK启动时从远程拉取，然后缓存在本地内存——但必须加密缓存。
3. 密钥的访问控制：不同应用、不同环境拿到的密钥范围不一样。开发环境只能读测试密钥，生产环境用HSM里的硬件密钥。

存储方案	优势	风险点
AWS KMS / 阿里云KMS	合规、自动轮换、审计日志	网络延迟、依赖云服务
HashiCorp Vault	动态密钥、租约管理	运维成本高
本地文件+主密钥加密	零外部依赖、低延迟	密钥泄露风险大

4.3 缓存模块：性能与安全的平衡木

加密操作本身就有不小的开销，尤其是确定性加密和国密算法。我在一次金融项目中，每秒加密请求峰值到了2万，引擎CPU直接飙满。原因很简单——每次加密都重新计算。

缓存模块能极大缓解这个问题。但缓存什么、怎么缓存，坑很多。

• 缓存对象：只缓存确定性加密的结果。随机加密每次结果不同，缓存没意义。
• 缓存粒度：以「字段类型+明文」作为key。比如 PHONE_13800138000 -> 加密密文。注意不要把用户ID放进去，容易关联。
• 缓存失效：密钥轮换时必须清空整个缓存。可以在缓存模块里注册一个监听器，收到密钥版本变更事件后调用 cache.invalidateAll()。
• 缓存大小：建议使用LRU策略，最大条目数不超过10000。我习惯把缓存的TTL设成5分钟，避免长期驻留敏感信息。

4.4 配置模块：让SDK学会「入乡随俗」

配置模块往往被忽视，但它决定了SDK能否在多环境（开发、测试、预发布、生产）无缝切换。

我建议配置模块做三件事：

1. 环境感知：自动读取环境变量 APP_ENV 或配置文件里的 env 字段。不同环境加载不同的密钥集合、缓存参数、日志级别。
2. 动态刷新：支持运行时重载配置，比如通过Redis发布订阅或者etcd watch。我遇到过生产环境需要紧急关闭某个算法的场景，如果没有热更新，就得重启应用——那是多可怕的事。
3. 配置校验：启动时做完整性校验。比如检查密钥版本号是否连续、算法名是否合法、缓存TTL是否大于0。不能让SDK在错误的配置下运行。

配置模块的典型结构如下：

sdk:
  env: prod
  engine:
    algorithm: AES-GCM
    keyVersion: 2
  cache:
    enabled: true
    maxSize: 5000
    ttlMinutes: 5
  keyManager:
    provider: vault
    vaultAddr: https://vault.internal:8200
    vaultToken: ${VAULT_}

四个模块如何协同？

下面这张SVG图概括了加密SDK核心架构的数据流：

这张图里，配置模块是「大脑」，告诉其他模块该怎么跑。加密引擎是「心脏」，承担核心计算。密钥管理是「保险柜」，只给引擎临时钥匙。缓存是「记忆体」，减少重复劳动。密钥轮换事件由密钥管理发出，缓存模块监听到后立即清空——这个联动机制特别重要。我以前漏掉它，导致旧密钥轮换后，缓存里还躺着用旧密钥加密的数据，新查询回来解密失败，排查了好几个小时。

模块间接口契约

为了让四个模块能独立演进，我建议用接口定义好交互规范：

模块	暴露接口	核心方法
加密引擎	CryptoProvider	encrypt(fieldType, plaintext) / decrypt(ciphertext)
密钥管理	KeyProvider	getDataKey(version, algorithm) / rotateKey()
缓存模块	CacheProvider	get(key) / put(key, value, ttl) / clearAll()
配置模块	ConfigProvider	getString(path) / getInt(path) / watch(key, listener)