第3章：SDK架构设计——对象存储SDK的通用分层架构、核心接口抽象、传输协议选择

好，前面我们聊完了加密算法的选型和密钥管理的基本思路。现在该动真格的了——设计一个真正能用的对象存储加密上传下载SDK，它的骨架长什么样？

我见过不少团队，上来就写代码，结果写到一半发现：上传的逻辑和加密的逻辑耦合在一起，换个后端就要重写一半；想加个进度回调，发现无处安放。说白了，就是架构设计没想清楚。一个好的SDK架构，应该像乐高积木一样——各个模块各司其职，互相独立，又能灵活组合。

3.1 通用分层架构：SDK的“三明治”

我个人习惯把SDK分成三层，你也可以理解成“三明治模型”：

• 接口层（最上层）： 对外暴露的API。提供简单、统一的上传、下载、删除、列举等操作。用户只需要关心业务逻辑，不用管底层细节。
• 核心层（中间层）： 逻辑处理中心。负责加密/解密、数据分片、断点续传、重试策略、鉴权签名等核心功能。这是SDK的“大脑”。
• 传输层（最底层）： 对接存储后端。处理HTTP/HTTPS协议、连接池、DNS解析、TLS握手等。说白了，就是怎么把数据发出去和收回来。

我在项目中见过很多团队，直接拿一个开源的HTTP SDK（比如axios、okhttp）当底层，然后在业务代码里直接调用这个SDK，中间夹揉了一大堆加密和鉴权逻辑。结果就是，换一个后端存储服务，代码根本没法复用，整个推倒重来。嗯，这就是典型的“分层没做好”。

3.2 核心接口抽象：多路复用与统一桩

接口层的设计至关重要。你不能给用户暴露一个“大而全”的类，里面上百个方法，用户看了头皮发麻。好的接口抽象，应该是“小而美”的。

我推荐使用多路复用统一桩的模式：

• 定义三个基础接口：ObjectStorage（存储操作）、EncryptionEngine（加密操作）、TransferManager（传输管理）。
• ObjectStorage 接口提供 upload()、download()、delete()、list() 等业务方法。
• EncryptionEngine 接口提供 encrypt()、decrypt()、keyEnvelope() 等方法。
• TransferManager 接口负责处理并发、重试、进度回调。

这三个接口的组合，就是SDK的“统一桩”。用户通过依赖注入，可以自由组合不同的实现。

// 例子：核心接口抽象（Java风格伪代码）
public interface ObjectStorage {
    AdapterResponse upload(String bucketName, String key, InputStream data, ObjectMetadata metadata);
    AdapterResponse download(String bucketName, String key, OutputStream output);
    AdapterResponse delete(String bucketName, String key);
    AdapterResponse list(String bucketName, String prefix);
}

public interface EncryptionEngine {
    CipherResult encrypt(byte[] plaintext, EncryptionContext context);
    byte[] decrypt(byte[] ciphertext, EncryptionContext context);
    KeyEnvelope getKeyEnvelope(String keyId);
}

public interface TransferManager {
    void setMaxConnections(int max);
    void setRetryStrategy(RetryStrategy strategy);
    CompletableFuture<ProgressResponse> uploadWithProgress(ObjectStorage storage, String bucket, String key, InputStream data);
    CompletableFuture<ProgressResponse> downloadWithProgress(ObjectStorage storage, String bucket, String key, OutputStream output);
}