第四章 适配策略设计：整体适配方案选择

好，我们进入实际动手前的关键环节——选择适配策略。说白了，就是“旧密钥”和“新SDK”之间这层中间代码到底长什么样。

我记得刚开始接手这类迁移项目时，总是冲动地想直接改SDK调用方代码。结果改了几百处，还没跑通一个接口，反而引了一堆新Bug。后来才意识到，选对适配模式比写代码重要得多。

三种主流适配方案

根据我的经验，旧密钥适配新SDK主要有三种打法：封装层（Wrapper）、转换层（Transformer）和桥接模式（Bridge）。它们各有脾气，选错了后续维护会非常痛苦。

方案	核心思想	适用场景	我踩过的坑
封装层	在旧SDK外层包一个新接口	新旧接口参数结构类似	参数名映射遗漏导致运行时异常
转换层	中间加一层数据格式转换	数据模型差异大，协议不同	时间戳精度丢失引发线上问题
桥接模式	抽象接口与实现解耦，动态选择	需要同时兼容新旧版本	接口膨胀后难以维护

方案一：封装层（Wrapper）——最快上手

封装层，说白了就是写一个类，把旧SDK的所有方法“包”起来，对外暴露和新SDK一致的接口。内部实现里直接调用旧SDK的逻辑。

我个人习惯在项目初期这么干——快速验证迁移流程。你看看这个伪代码就明白了：

class OldSdkWrapper:
    def __init__(self):
        self._sdk = OldSdk()  # 旧SDK实例

    def encrypt(self, data: bytes, key_id: str) -> bytes:
        # 把新接口参数映射到旧接口
        legacy_key = self._map_key_id(key_id)
        return self._sdk.legacy_encrypt(data, legacy_key)

    def _map_key_id(self, key_id):
        # 简单的映射表
        mapping = {"key_v2": "key_v1"}
        return mapping.get(key_id, key_id)

不过，封装层也有硬伤——如果新旧SDK的协议（比如签名算法、序列化格式）不一样，光封装根本解决不了。这时候就得请出转换层了。

方案二：转换层（Transformer）——处理差异

转换层比封装层多干一件事：数据格式转换。例如，旧SDK返回XML格式的密钥信息，新SDK只要JSON，那你必须加一个“翻译官”。

我曾经在一个支付项目中碰到过这种情况：旧SDK的时间戳是秒级Integer，新SDK要毫秒级Long。如果直接用封装层，转换逻辑会散落在各处。我画了一个专门的转换器：

class KeyTransformer:
    @staticmethod
    def to_new_format(legacy_data: dict) -> dict:
        return {
            "key_id": legacy_data["key_id"],
            "created_at": legacy_data["timestamp"] * 1000,  # 秒转毫秒
            "algorithm": "AES-256" if legacy_data["algo"] == 1 else "SM4"
        }

转换层的缺点是：它和业务逻辑耦合得比较紧。如果你既要转换数据，又要控制调用流程（比如重试、熔断），那就得考虑桥接模式了。

方案三：桥接模式（Bridge）——灵活的庖丁解牛

桥接模式是这三种里最“高级”但也是最重的。它的核心思想是将“抽象”和“实现”分离。举个例子：抽象层定义加密接口，实现层可以是旧SDK，也可以是新SDK。通过组合而不是继承来灵活切换。

嗯，这里我直接贴一个简化版的UML关系，你理解一下结构：

class EncryptionAbstraction:
    def __init__(self, implementor):
        self._impl = implementor

    def encrypt(self, data):
        return self._impl.do_encrypt(data)

class OldImplementor:
    def do_encrypt(self, data):
        return OldSdk.encrypt(data)

class NewImplementor:
    def do_encrypt(self, data):
        return NewSdk.encrypt(data)

# 使用
bridge = EncryptionAbstraction(OldImplementor())
result = bridge.encrypt(b"hello")

这样做的最大好处是：如果你想从旧SDK逐步切换到新SDK，只需要换一个实现对象，上层业务代码完全不用改。

不过，桥接模式不宜滥用。我记得一个项目里用了五层桥接，最后没人能看懂到底调用的是哪个实现。如果你只有两个SDK要适配，封装层或转换层就够了。

一图看懂三种策略

下面这张图我把三种方案的核心差异画出来了，建议你保存下来做选择时的参考：

如何选择？一张决策表

你想想看，实际项目里往往不是非黑即白。我列了一个快速决策表，照着勾选就好：

评估条件	封装层	转换层	桥接模式
旧新接口参数基本一致	★ 首选	可接受	过度设计
旧新协议/数据格式不同	不推荐	★ 首选	可选（配合转换层）
需要灰度切换（新旧并存）	无法支持	配合策略模式	★ 天然支持
团队维护能力弱	★ 最简单	中等	★ 不推荐（复杂）