20、头文件中的版本控制：版本宏定义、API 版本兼容性处理

版本控制这事儿，说起来简单，做起来全是坑。我见过太多项目，头文件改了一版又一版，结果下游模块编译不过，或者运行时行为诡异。说白了，头文件就是模块之间的契约。契约变了，得让所有人都知道。

今天咱们就聊聊，怎么在头文件里把版本控制做好。我自己的经验是，这事得从三个层面入手：版本怎么定义、怎么通知调用方、怎么处理兼容性。

20.1 版本宏定义的基本套路

先看一个最基础的版本宏定义。我个人习惯用三位版本号：主版本、次版本、补丁版本。

// version.h
#ifndef VERSION_H
#define VERSION_H

#define MODULE_VERSION_MAJOR  2
#define MODULE_VERSION_MINOR  1
#define MODULE_VERSION_PATCH  3

// 组合成一个整数版本号，方便比较
#define MODULE_VERSION ((MODULE_VERSION_MAJOR << 16) | \
                        (MODULE_VERSION_MINOR << 8)  | \
                        (MODULE_VERSION_PATCH))

// 字符串版本号，方便打印
#define MODULE_VERSION_STR "2.1.3"

#endif // VERSION_H

你想想看，为什么要把版本号组合成一个整数？因为比较大小方便啊。比如调用方可以写：

#if MODULE_VERSION >= 0x020100
    // 使用 2.1.0 之后才有的新接口
#else
    // 使用旧接口
#endif

嗯，这里要注意：版本号组合时，每个字段不要超过 8 位（0-255）。我在项目中遇到过有人把补丁版本写到 300 多，结果溢出，版本比较全乱套了。

20.2 API 版本兼容性声明

光有版本号还不够。调用方需要知道：我这个版本到底改了啥？哪些是新增的，哪些是废弃的？

我建议在头文件里明确声明兼容性信息。比如这样：

// module.h
#ifndef MODULE_H
#define MODULE_H

#include "version.h"

/*
 * 兼容性说明：
 * - 2.0.0: 重构了初始化接口，旧版 init() 废弃
 * - 2.1.0: 新增 set_config() 接口
 * - 2.1.3: 修复 get_status() 返回值 bug
 */

// 废弃标记宏
#define DEPRECATED __attribute__((deprecated))

// 2.0.0 之前的老接口，标记为废弃
DEPRECATED int init(int mode);

// 2.0.0 引入的新接口
int module_init(const char *config);

// 2.1.0 新增
int set_config(int key, int value);

// 一直存在的接口
int get_status(void);

#endif // MODULE_H

这里用了 __attribute__((deprecated))，编译时会有警告。调用方一看就知道：哦，这个接口快没了，得赶紧换。

20.3 版本兼容性检查机制

有时候，调用方和库的版本不匹配，运行时才会暴露问题。我建议在头文件里加一个编译期检查。

// module.h
#define MODULE_REQUIRE_VERSION(major, minor, patch)                     \
    extern int __module_version_check_##major##_##minor##_##patch;      \
    typedef int __module_version_check_type_##major##_##minor##_##patch \
        [(MODULE_VERSION >= ((major << 16) | (minor << 8) | patch)) ? 1 : -1]

// 调用方可以这样声明：要求至少 2.1.0
MODULE_REQUIRE_VERSION(2, 1, 0);

这个技巧有点绕，但很实用。它利用了一个特性：数组长度不能为负数。如果版本不满足，编译就会报错。我曾经在一个嵌入式项目里用这个办法，成功拦截了三次版本不匹配的集成问题。

20.4 运行时版本查询

编译期检查还不够。有些场景下，库是动态加载的，或者调用方和库是分开编译的。这时候需要运行时查询版本。

// module.h
typedef struct {
    int major;
    int minor;
    int patch;
    const char *version_str;
} module_version_t;

// 运行时获取版本信息
const module_version_t* module_get_version(void);

// 运行时检查版本兼容性
// 返回 0 表示兼容，非 0 表示不兼容
int module_check_compatibility(int req_major, int req_minor, int req_patch);

实现文件里可以这样写：

// module.c
static const module_version_t s_version = {
    .major = MODULE_VERSION_MAJOR,
    .minor = MODULE_VERSION_MINOR,
    .patch = MODULE_VERSION_PATCH,
    .version_str = MODULE_VERSION_STR,
};

const module_version_t* module_get_version(void) {
    return &s_version;
}

int module_check_compatibility(int req_major, int req_minor, int req_patch) {
    // 主版本不同，肯定不兼容
    if (req_major != MODULE_VERSION_MAJOR) {
        return -1;
    }
    // 次版本：调用方要求的次版本不能大于当前次版本
    if (req_minor > MODULE_VERSION_MINOR) {
        return -2;
    }
    // 补丁版本同理
    if (req_patch > MODULE_VERSION_PATCH) {
        return -3;
    }
    return 0;
}

20.5 版本兼容性策略总结

说了这么多，咱们用一张图来梳理一下整体思路。

20.6 实际项目中的避坑指南

最后，分享几个我踩过的坑。

• 版本号别乱改。 我曾经在一个项目里，有人为了「好看」把版本号从 1.0.0 直接跳到 2.0.0，结果下游所有模块的兼容性检查都炸了。版本号变更要有实际意义。
• 废弃接口别急着删。 至少保留两个版本周期。我一般会在废弃时加一条编译警告，再下一个版本才真正移除。
• 运行时检查别省略。 编译期检查只能防住一起编译的情况。如果库是动态加载的，或者调用方用了旧头文件，运行时检查就是最后一道防线。
• 版本信息要可打印。 我习惯在模块初始化时打印版本号，这样看日志就能知道当前跑的是哪个版本，排查问题快很多。

好了，这一章就到这里。版本控制这事，说起来简单，但真正做好需要养成习惯。希望这些经验对你有帮助。

---

公众号:蓝海资料掘金营，微信deep3321