第3章：SDK架构设计原则：分层、可扩展、平台无关与接口规范

聊到SDK架构，很多人的第一反应是“能跑就行”。但你要是做过几年的SDK交付，就会明白——架构设计才是决定这个SDK能活多久的关键。我记得刚入行那会儿，有个项目急着上线，团队把所有逻辑都揉在一个大模块里。后来客户要加一个国密算法的支持，我们改了整整两周，还引入了一堆回归bug。那之后，我就对架构设计特别较真。

这一章，我们来拆解字段级加密SDK的核心设计原则：分层设计、可扩展、平台无关、接口规范。这四个原则不是摆设，它们是你在实际项目中少走弯路的基石。

3.1 分层设计：各司其职，互不干扰

分层设计，说白了就是把SDK拆成几个独立的功能层。每个层只管自己的事，层与层之间通过定义好的接口通信。你想想看，如果加解密逻辑和网络传输混在一起，那调试的时候得多头疼？

通常，字段级加密SDK可以划分为三层：

1. 用户接口层（User API Layer）：对外暴露的API，比如 encryptField()、decryptField()。这一层负责接收用户请求，做参数校验，然后交给下层处理。
2. 核心业务层（Core Logic Layer）：加解密引擎、字段解析器、密钥管理逻辑。这是SDK的心脏，所有安全策略都在这里实现。
3. 基础设施层（Infrastructure Layer）：底层密码算法库（如OpenSSL、BoringSSL）、序列化工具、日志系统。这一层可以被替换，不影响上层。

3.2 接口规范：稳、简、明、容

接口是SDK和用户之间的契约。我个人习惯把接口规范总结为四个字：稳、简、明、容。

• 稳（Stable）：接口签名一旦发布，尽量不要变。如果要变，必须做版本标记（如 @Deprecated 或版本号标识），并且给用户一个过渡期。
• 简（Simple）：函数参数不要超过5个。如果确实需要更多配置，建议用配置对象（Configuration Object）或建造者模式（Builder Pattern）。
• 明（Explicit）：函数名称要能直观反映其作用，比如 encryptField 而不是 processData。返回值要清晰地表达成功或失败状态。
• 容（Tolerant）：对输入数据做合理的容忍度处理。比如字段为空时是返回默认值还是抛出异常，要有明确的文档说明。

3.3 可扩展：为未来的变化留好接口

没有哪个SDK能一开始就覆盖所有场景。可扩展性意味着：在不修改现有代码的前提下，能够增加新功能。这通常靠抽象接口和插件模式来实现。

我建议你在设计时，至少为以下三个部分预留扩展点：

扩展点	抽象接口示例	扩展场景
密码算法	CipherProvider	自定义加解密算法、国密算法支持
密钥管理	KeyManager	对接KMS、本地文件、HSM
序列化/反序列化	DataSerializer	Protobuf、FlatBuffers、自定义格式

我曾经遇到一个客户，他们所有的敏感字段都用了自定义的编码方式。如果没有可扩展的 DataSerializer 接口，那个项目基本就黄了。所以，扩展点不要等到用户提需求时才加，一开始就设计好。

3.4 平台无关：一次编写，到处运行

字段级加密SDK通常会运行在不同的平台上：Linux服务器、Windows Server、macOS开发机，甚至嵌入式设备。平台无关性要求SDK不依赖特定操作系统的特性。

这里有几个硬性要求：

• 使用标准库：避免调用平台特定的API（如Windows的 CryptAPI 或Linux的 /dev/random）。如果需要随机数生成，优先使用语言标准库中的安全随机生成器。
• 路径与文件：所有文件路径操作都用跨平台库（如Java的 File.separator，或C++中的 / 统一处理）。
• 内存与字节序：确保加解密过程不依赖小端或大端字节序。常用的做法是网络字节序（Big Endian）作为通信标准。

3.5 各原则之间的关系

这四个原则不是孤立存在的。分层设计为可扩展提供了基础框架，接口规范保证了各层之间的通信清晰可控，而平台无关则确保了整个SDK可以在不同环境中被部署。你可以把分层设计看作是骨架，接口规范是关节，可扩展性是预留的生长空间，平台无关性则是这个身体对环境的适应能力。

下面这张图可以帮你快速理解它们之间的关系：

3.6 避坑建议

最后，分享几个我在实际项目中积累的经验，希望能帮你少走些弯路：

• 不要一开始就定义所有接口：我见过不少团队在架构阶段就列出了几十个接口，结果大多数没用到。建议先实现一个最小可用版本，再根据实际需求逐层抽象。
• 分层要避免“跨层调用”：比如用户接口层直接调用基础设施层的密码库，这是典型的耦合，后续维护起来会很痛苦。
• 平台无关不等于“放弃性能”：有些跨平台方案会引入额外的封装成本。如果某个平台占绝大多数，可以考虑用条件编译做针对性优化，但必须保证在不修改上层代码的情况下切换。