3. SDK整体架构：核心模块与依赖关系
好，咱们直接切入正题。SDK的整体架构，说白了就是搞清楚三个事：谁负责干活、谁管钥匙、谁负责看配置文件。我习惯把这三兄弟叫做加密引擎、密钥管理接口和配置解析器。你想想看，如果这三个模块配合不好，上层业务调用时就会出现各种莫名其妙的问题。
3.1 三大核心模块概述
我个人习惯把加密引擎看成SDK的心脏。它负责具体的加解密运算、数据校验、内存安全处理。密钥管理接口则更像是保险柜管理员，不直接处理业务数据，但它决定你能用什么钥匙、钥匙从哪来。配置解析器则是个翻译官，把外部的XML或JSON配置转成引擎能理解的对象。
| 模块名称 | 职责 | 典型实现 |
|---|---|---|
| 加密引擎 | 执行加密/解密、哈希、签名校验 | 基于OpenSSL或国密SM系列库封装 |
| 密钥管理接口 | 密钥获取、轮换、缓存、销毁 | 对接KMS / 本地HSM / 内存策略 |
| 配置解析器 | 读取并验证SDK运行时参数 | YAML加载器 + Schema校验器 |
关键点：三个模块之间没有循环依赖。加密引擎不直接调用配置解析器，而是通过依赖注入拿到配置对象。这样做的目的是为了单元测试时能轻松 Mock 掉配置来源。
3.2 加密引擎内部细节
加密引擎不是简单调个AES就完事了。它至少需要处理：算法选择、模式选择、填充策略、初始化向量(IV)生成、分段处理、以及内存清理。嗯，这里要注意，很多人在实现时忘了内存清理这一步。
我曾经在一个金融项目中遇到过一个问题：SDK加密完数据后，临时密钥还留在栈内存里没被主动擦除。按理说函数返回后栈帧会被覆盖，但JVM或托管环境不一定能立即回收。这就给侧信道攻击留下了口子。从那以后，我在引擎层强制加上了SecureZap方法，所有临时缓冲区在释放前都会被覆写为0x00。
核心接口通常长这样：
public interface CryptEngine {
byte[] encrypt(byte[] plaintext, CryptContext ctx);
byte[] decrypt(byte[] ciphertext, CryptContext ctx);
void wipe(byte[] sensitiveData);
}你可能会问，为什么要把CryptContext单独抽出来？因为不同的列可能用不同的算法和密钥ID，把这些参数打包成一个上下文对象，能减少接口参数数量，也方便扩展。
3.3 密钥管理接口的层次
密钥管理接口我分为两层：上层是KeyResolver，下层是KeyProvider。Resolver 负责逻辑判断（比如根据列ID找对应的密钥版本），Provider 负责实际的密钥存取（比如从KMS拉取或从本地文件加载）。
为什么要分层？说白了就是为了解耦。有一次我们在做密钥轮换时，发现Resolver里混了网络调用代码，导致Resolver单元测试必须启动一个模拟KMS服务。后来我强制把Provider剥离出来，单元测试时直接注入一个返回固定密钥的MockProvider就搞定了。
避坑指南：千万不要在KeyResolver里缓存密钥对象超过5分钟。我曾经因为缓存时间设置太长，导致密钥轮换后业务层还在用旧密钥加密，结果解密时全部失败。正确的做法是：缓存密钥引用，但强制设置TTL并且提供主动刷新接口。
3.4 配置解析器的设计思路
配置解析器看起来简单，但它往往是SDK出错的源头之一。我见过太多因为配置项写错一个字母导致加密引擎初始化失败的案例。所以配置解析器的核心不是读取，而是校验和容错。
我设计的配置解析器内部包含三个步骤：
- 加载：支持多来源优先级，命令行参数优先于环境变量，环境变量优先于配置文件。
- 校验：每个配置项都有类型约束和取值范围校验，比如算法名必须是枚举值，密钥长度必须是128或256。
- 规范化：将驼峰、下划线、环境变量名统一转为内部使用的标准字段名。
警告：配置解析器不能抛出未处理的异常。如果某个配置项校验失败，应该使用降级策略（比如使用默认值）并输出WARN日志，而不是直接让SDK启动失败。生产环境中，很多微服务是在启动时一次性加载SDK配置的，一个校验异常就可能让整个Pod陷入CrashLoopBackOff状态。
3.5 类图与依赖关系
好了，理论说完了，咱们看看类图。我下面用一张SVG来展示三个核心模块之间的类关系与依赖方向。
从这张图你可以看到：加密引擎和密钥管理接口之间是强依赖关系，引擎需要调用接口获取密钥后才能执行加解密。而配置解析器可以说是整个SDK的启动入口，它独自完成配置加载后，将结果注入给另外两个模块。虚线箭头表示可选依赖，我建议在初期设计时不要让配置解析器直接依赖密钥管理接口，否则配置解析器的测试会变得复杂。
3.6 依赖关系的实际落地经验
我记得在某金融项目里，配置解析器卡了很久。因为项目要求同时支持本地文件配置和配置中心动态推送。当时我直接让配置解析器内部持有一个ConfigChangeListener接口，实现热更新。这导致加密引擎和密钥管理接口必须也支持运行时刷新，不能把配置结果缓存死。
最后我总结了一条规则：主调用链上不要有阻塞式的配置加载。SDK启动时先用默认配置把引擎初始化起来，配置解析器异步完成完整加载后再做热替换。这样即使配置中心挂了，SDK也能用默认配置继续工作，不会影响业务连续性。
避坑指南：我曾经有一次把配置解析器的加载逻辑放在了加密引擎的构造函数里，结果SDK启动时如果配置文件格式不对，整个应用都启不来。正确的做法是：配置解析器独立初始化，并提供一个isReady()方法来标识是否加载成功。引擎构造函数只需要接收一个Config对象，别在构造函数里搞网络I/O或文件读取。
好了，以上就是第3章SDK整体架构的核心内容。记住这三个模块各自的职责，以及它们之间不能有循环依赖这个原则，后面几章我们会深入到每个模块的实现细节里去。