第四节：加密SDK架构设计——分层架构与模块划分
大家好。咱们直接进入正题。加密SDK的架构设计，说白了就是决定“代码怎么组织、模块怎么分工”。这一块如果没想清楚，后面维护起来会相当痛苦。
我个人习惯把加密SDK分成四个层。为什么要分层？你想想看，如果所有逻辑都堆在一个大函数里，密钥生成、加密运算、网络传输全混在一起……那简直是一场噩梦。
分层的好处很明显：每一层只干自己该干的事。上层不关心底层怎么实现，底层也不越权去管业务逻辑。我在某项目中曾经因为没做好分层，导致换了一个加密算法就要改三四个模块——嗯，从那以后我就再也不敢偷懒了。
4.1 整体分层结构
下面这张图是我画的一个典型架构。别嫌它简单，实际产品里核心骨架就是这个样子的。
你从图上能直观看到，每一层都只跟紧邻的层通信。上层调用下层，下层不能反向调用上层——这是硬约束。为什么？因为一旦出现循环依赖，测试、替换、升级全都变得不可控。
4.2 各层职责详解
下面我用一个表格把每层该干什么、不该干什么说清楚。有些边界问题，实际开发中很容易踩坑。
| 层级 | 核心职责 | 不该做的事 |
|---|---|---|
| 表示层 | 对外暴露API、参数校验、异常转换、版本兼容 | 不执行任何加密运算，不管理密钥 |
| 业务编排层 | 密钥协商流程、算法选择、数据分片、重试逻辑 | 不直接操作底加密算法，不做网络I/O |
| 核心加密层 | 调用密码学库、执行加解密、哈希签名 | 不涉及业务逻辑，不持久化密钥 |
| 基础设施层 | 密钥安全存储、随机数生成、内存擦除、日志审计 | 不暴露加密算法给上层 |
个人经验：我在一个早期项目中，把密钥管理放到了核心加密层。结果一次密钥轮换，几乎把所有逻辑都改了一遍。后来我把它单独拆到基础设施层——从那以后，换密钥方案只需要改一个模块。这算是一个比较惨痛的教训。
4.3 模块划分的具体实践
说完了层，咱们再来聊聊模块。每个层下面还可以进一步拆分出独立的模块。我一般会按照“高内聚、低耦合”的原则来切，每个模块只关注一个职责。
表示层的模块：
- API入口模块：处理外部传入的参数，做格式校验、空值检查。这一层尽量少做事，快速失败是最好的设计。
- 版本适配模块：当SDK升级时，兼容旧版本的API签名。这在大厂SDK里几乎必备。
业务编排层的模块：
- 密钥协商模块：像ECDH握手、会话密钥生成等。这块其实是安全重点，容易被黑产利用。
- 算法选择模块：根据用户配置或协商结果，动态选择AES还是SM4，GCM还是CBC。顺便说一句，GCM模式在性能上优于CBC，而且自带认证——你想想看，为什么还有人用CBC？
- 数据分片模块：大文件加密时，需要切分后逐块处理。这里的边界处理很容易出bug。
核心加密层的模块：
- 对称加密模块：AES、SM4等算法的封装。注意，所有算法实现都依赖底层密码学库（比如OpenSSL、BoringSSL），不要在SDK里自己实现加密算法。
- 非对称加密模块：RSA、ECC、SM2。签名和验签的逻辑也放这里。
- 哈希模块：SHA256、SM3。走数据完整性校验时用到。
基础设施层的模块：
- 密钥存储模块：支持内存存储、文件存储、硬件安全模块（HSM）或者TEE。这个模块必须做严格的权限控制。
- 随机数生成模块：一定要使用操作系统提供的安全随机数生成器，比如
/dev/urandom或CryptGenRandom。千万不要用rand()——嗯，我曾经在code review中看到过，直接打回去重做了。 - 日志审计模块：记录关键操作的时间、操作类型、结果。注意不要记录密钥本身的内容。
模块间调用关系示例（伪代码）：
// 表示层：接收到加密请求
String encryptedData = sdk.encrypt(publicKey, plainData);
// 业务编排层：选择算法并调度
byte[] key = keyNegotiationModule.exchangeKey(publicKey);
String algorithm = algorithmSelector.pick("AES-256-GCM");
byte[] cipherText = coreEngine.encrypt(algorithm, key, plainData);
// 核心加密层：执行实际加密
byte[] raw = aes256Gcm.encrypt(key, plainData, iv);
// 基础设施层：提供随机数和密钥
byte[] iv = secureRandomGenerator.generate(12);
key = keyStore.getCurrentKey();4.4 分层架构的避坑指南
讲完了“应该怎么做”，再说说“别怎么做”。这部分都是我用真金白银换来的。
避坑一：我曾经在一个加密SDK里，把日志记录功能放在核心加密层。结果上线后发现，每次加密都会把明文以DEBUG日志打出来……审计团队直接发了一封严重安全事件邮件。这就是典型的越层问题——日志应该放在基础设施层，并且必须由配置开关控制是否开启。
避坑二：密钥绝不能混用。我记得有次项目急着上线，同事把会话密钥和用户密钥存在同一个结构体里，加解密过程里不小心把会话密钥当成了签名私钥……在测试环境还好，上了生产环境，直接导致一批证书签名验证失败。从那以后，我强制要求密钥管理模块必须在物理上隔离不同类型密钥的存储位置。
避坑三：跨层数据拷贝要小心。我曾经遇到一个性能问题，查到最后发现是每一层都复制了一份原始数据。你想想看，如果明文有10MB，每层拷贝一次，处理完就变成40MB了。现在我会在进入核心加密层之前只传指针或者引用，直到最后一刻才做必要的复制。而且，操作完后立即调用memset或SecureZeroMemory擦除敏感数据。
4.5 模块间的安全边界
最后聊聊安全边界。分层架构不只是为了代码整洁，也是为了安全。具体来说，要做到以下几点：
- 最小化暴露：每个模块只暴露必要的接口，其他接口一律用
internal或private封装。 - 参数校验前置：所有传入的参数在表示层就必须校验完毕，不要让非法参数穿透到核心层。
- 异常不泄露敏感信息：核心加密层抛出的异常，在表示层要统一转换成通用错误码。我在某项目中遇到过把“密钥索引越界”这种信息直接返回给前端的情况——这种信息对攻击者来说就是地图。
- 审计日志：关键操作必须记录，但记录内容要过滤掉密钥和明文。我建议在基础设施层做好日志脱敏。
嗯，关于架构设计，核心就是这些了。结构对了，后面再怎么迭代都不会太乱。如果一上来就急着写功能，架构却没想清楚……那你会经历一段非常痛苦的时期。这个我可是深有体会。