23、遗留接口的封装：外观模式应用、适配器模式、版本兼容性处理

好，咱们今天聊一个实战性很强的话题——遗留接口的封装。

说实话，我在很多项目里都见过这种场景：系统跑了七八年，底层接口换了好几轮，但上层调用方不敢动。为什么？一动就崩。你想想看，一个接口被几十个模块引用，谁敢随便改它的签名？

那怎么办？封装。说白了，就是在旧接口外面包一层新皮，让新旧系统能和平共处。今天我就把三种最常用的手法掰开揉碎讲清楚：外观模式、适配器模式，还有版本兼容性处理。

23.1 外观模式：给混乱的遗留接口一个干净的门面

外观模式，英文叫 Facade Pattern。它的核心思想很简单：提供一个统一的、简化过的高层接口，把底层一堆乱七八糟的调用藏起来。

我在一个金融交易系统里遇到过这种情况。老系统里有十几个初始化函数，调用顺序还不能错：先调 init_log()，再调 init_db()，然后 init_network()……新来的同事每次都要翻文档，还经常漏掉某个步骤。我当时就写了一个 SystemFacade，把所有这些初始化步骤包在一个 system_init() 里。从此世界清净了。

来看一个典型的代码示例：

/* 遗留的多个初始化接口 */
void init_logger(void);
void init_database(void);
void init_network(void);
void init_config(void);

/* 外观封装 */
void system_init(void) {
    init_logger();
    init_database();
    init_network();
    init_config();
    printf("[Facade] 系统初始化完成\n");
}

/* 调用方只需要一行 */
int main() {
    system_init();  /* 背后干了四件事，但调用者不用关心 */
    /* ... 业务逻辑 ... */
    return 0;
}

嗯，这里要注意：外观模式不是为了加一层而加一层。它的前提是底层接口确实混乱、调用顺序复杂、或者有重复的样板代码。如果你只是简单地把一个函数包成另一个函数，那叫脱裤子放屁。

23.2 适配器模式：让新旧接口能对上话

适配器模式，Adapter Pattern。这个更常见——老接口的签名和新接口对不上，怎么办？写一个适配器，把老接口的调用转换成新接口能理解的形式。

我曾经接手过一个项目，老系统用 int send_data(char* buf, int len) 发数据，新系统要求用 int transmit(const uint8_t* data, size_t size)。参数类型不一样，顺序也不一样。直接改老接口？几百个调用点等着你改。写适配器？半小时搞定。

/* 遗留接口 */
int send_data(char* buf, int len) {
    /* 老实现，不能动 */
    return 0;
}

/* 新接口期望的签名 */
int transmit(const uint8_t* data, size_t size);

/* 适配器：把老接口包装成新接口的样子 */
int transmit_adapter(const uint8_t* data, size_t size) {
    /* 注意：const 转 non-const 要小心，这里假设内部不会修改 */
    return send_data((char*)data, (int)size);
}

适配器模式还有一种常见变体——对象适配器。不是直接改函数签名，而是通过一个结构体包装：

/* 对象适配器示例 */
typedef struct {
    int (*old_send)(char*, int);
    int (*old_recv)(char*, int);
} LegacyProtocol;

typedef struct {
    int (*new_transmit)(const uint8_t*, size_t);
    int (*new_receive)(uint8_t*, size_t);
} NewProtocol;

/* 适配器结构体，同时持有新旧接口 */
typedef struct {
    LegacyProtocol* legacy;
    NewProtocol*    adapted;
} ProtocolAdapter;

int adapter_transmit(ProtocolAdapter* self, const uint8_t* data, size_t size) {
    return self->legacy->old_send((char*)data, (int)size);
}

这种写法更灵活，适合接口数量多、需要动态切换的场景。

23.3 版本兼容性处理：让老接口慢慢退休

版本兼容性处理，说白了就是让新旧接口能共存一段时间。你不能今天改了接口，明天就让所有调用方都跟着改。现实项目里，接口的废弃周期通常是半年到一年。

我常用的手法有三种：

手法	适用场景	风险等级
版本号路由	接口参数变化较大	低
编译开关	临时过渡，短期共存	中
废弃标记 + 警告	逐步淘汰老接口	低

23.3.1 版本号路由

在接口里加一个版本号参数，根据版本号走不同的逻辑分支：

#define API_VERSION_1 1
#define API_VERSION_2 2

int process_data(int version, void* data, size_t len) {
    switch (version) {
        case API_VERSION_1:
            /* 老逻辑，保持原样 */
            return legacy_process(data, len);
        case API_VERSION_2:
            /* 新逻辑，更安全、更快 */
            return new_process((uint8_t*)data, len);
        default:
            fprintf(stderr, "未知版本号: %d\n", version);
            return -1;
    }
}

我个人习惯在版本号路由里加一个日志，记录哪些调用方还在用老版本。这样方便后续推动升级。

23.3.2 编译开关

用宏控制新旧接口的编译：

/* 头文件中 */
#if defined(USE_NEW_INTERFACE)
    int new_process(uint8_t* data, size_t len);
#else
    int old_process(char* data, int len);
#endif

/* 实现文件中，适配层统一转换 */
int process_wrapper(char* data, int len) {
#if defined(USE_NEW_INTERFACE)
    return new_process((uint8_t*)data, (size_t)len);
#else
    return old_process(data, len);
#endif
}

23.3.3 废弃标记 + 警告

这是最温和的方式。在头文件里用 __attribute__((deprecated)) 标记老接口，编译时给调用方输出警告：

/* legacy.h */
__attribute__((deprecated("请使用 new_process() 替代")))
int old_process(char* data, int len);

调用方编译时会看到类似这样的警告：

warning: 'old_process' is deprecated: 请使用 new_process() 替代 [-Wdeprecated-declarations]

嗯，这种方式的好处是温和，不破坏现有代码。坏处是——很多团队对警告视而不见。我曾经在一个项目里加了废弃标记，半年后检查，还有三分之一的人没改。最后没办法，我直接让老接口返回错误码，逼着他们升级。

23.4 三种手法的选择策略

你可能会问：这三种手法，什么时候用哪个？

我的经验是：

• 外观模式：适合底层接口多、调用顺序复杂、调用方只想「一键完成」的场景。比如系统初始化、批量数据导出。
• 适配器模式：适合接口签名不匹配、但逻辑基本一致的场景。比如换了第三方库、换了通信协议。
• 版本兼容性处理：适合接口本身在演进、需要逐步淘汰老版本的场景。这是长期维护的必修课。

这三种手法不是互斥的。我在实际项目中经常组合使用：外观模式封装一组遗留接口，内部用适配器对接新旧实现，再通过版本号路由支持逐步迁移。

23.5 知识体系总览

下面这张图总结了本章的核心逻辑：

最后说一句：封装遗留接口，不是为了炫技，而是为了让系统能安全地往前走。我见过太多项目，因为不敢动老接口，最后整个系统被拖死。封装不是逃避，而是给重构争取时间和空间。

---