兼容性的本质：API变更、ABI兼容性、源码兼容性、二进制兼容性
做SDK开发这些年，我踩过最大的坑，就是版本兼容。
你以为改个接口名、加个参数就完了？没那么简单。我见过因为一个结构体字段顺序调换了，导致整个 App 在用户设备上频繁闪退。也见过只是升级了一个小版本号，调用方代码全都要重新编译。
所以这一章，我们来捅破兼容性这层窗户纸。说白了，就是要搞清楚三件事：改了什么、怎么改的、改完对调用方有什么影响。
2.1 什么是兼容性？一个简单的定义
兼容性不是非黑即白的。我个人习惯把它分为四个层次：
- 源码兼容：调用方代码不用改，就能编译通过。
- 二进制兼容：调用方旧的 .o/.a/.so 文件，不用重新编译，直接链接新版本就能跑。
- API兼容：接口签名没变，入参出参语义一致。
- ABI兼容：底层调用约定、结构体内存布局、符号可见性等保持不变。
你想想看，这四个层次是层层递进的。源码兼容是最低要求，ABI兼容是最严苛的。
我在项目中遇到过不少团队，只关注了源码兼容性，觉得“编译过了就等于没问题”。结果一上线，线上崩溃率飙升。嗯，这是典型的只看表面、不看本质的坑。
核心思路：判断一个SDK版本升级是否是“安全升级”，不能只看 0patch 还是 minor，要看它在源码、ABI、行为三个维度上做了哪些变更。
2.2 API变更：最容易被发现的兼容性问题
API变更，说白了就是接口签名变了。这是调用方最先感知到的。
常见的API变更形式有：
- 方法名变了（
loginWithToken:改成authenticateWithToken:） - 参数类型变了（
int改成long） - 参数数量变了（新增了一个
options参数） - 返回值变了（从
bool改成int，语义也变了） - 抛出异常/错误码变了
为什么这类问题容易发现？因为编译期就能报错。Xcode 或者 Gradle 会直接告诉你找不到符号、类型不匹配。所以我一直建议：只要你的SDK改了公开API，一定要写 CHANGELOG，而且要写清楚“如何迁移”。
不过，有一种隐形的API变更，编译器检测不出来。我吃过这个亏：
避坑指南：我曾经在C语言SDK中把一个函数从 void func(int a) 改成了 void func(int a, int b)，但我保留了旧函数名的宏定义。结果调用方代码全部编译通过，但链接阶段因为参数压栈规则变了，运行时全乱套了。嗯，宏定义的“兼容”只是假象。
2.3 ABI兼容性：最隐蔽的杀手
ABI全称是 Application Binary Interface。它不像API那样写在头文件里，而是写在编译器的约定里。
我个人觉得，ABI兼容性是SDK兼容性中最难搞的部分。为什么？因为改对了代码，ABI也可能不兼容。
具体来说，ABI包含以下因素：
- 函数调用约定：参数怎么传（栈还是寄存器）、谁负责清理栈
- 结构体内存布局：成员顺序、对齐方式、填充字节
- 符号修饰规则：C++ name mangling 不同编译器不一样
- 虚函数表布局：虚函数在 vtable 中的顺序
- 异常处理机制：怎样抛异常、怎样展开栈
- 全局变量的地址偏移：Shared library 中全局变量的访问方式
你想想看，这些因素一旦变了一个，旧的二进制文件加载到新的SDK中，轻则段错误，重则静默数据损坏。
我在项目中遇到过最典型的例子：一个 iOS 静态库，升级时把 struct 里的一个 int 字段挪到了 char 字段前面。调用方没重新编译，结果用户手机上随机崩溃。原因就是结构体在内存中的偏移变了，读取到的全是乱码。
注意：C++ 类的 ABI 兼容性尤其脆弱。添加私有成员变量、修改基类、改变虚函数顺序，都会导致 ABI 不兼容。这个坑，C 语言开发者可能不太敏感，但做 C++ SDK 的人一定要警觉。
2.4 源码兼容性 vs 二进制兼容性
这两个概念经常被混淆。我做个简单的对比：
| 类型 | 核心关注点 | 检查时机 | 典型后果 |
|---|---|---|---|
| 源码兼容 | 调用方代码能否不经修改就编译通过 | 编译期 | 编译报错，直接暴露 |
| 二进制兼容 | 调用方已编译好的目标文件能否直接链接新版SDK | 链接期 + 运行时 | 链接警告、运行时崩溃 |
说白了，源码兼容是给开发者看的，二进制兼容是给用户的App看的。
举个例子：
- 你把一个函数的
int参数改成long，源码编译会报错，不满足源码兼容。 - 但你在 C 语言里添加一个新的函数，不修改任何旧函数接口，源码兼容没问题。但如果以动态库形式发布，旧的 App 没有这个新函数的符号，链接时就报错，不满足二进制兼容。
我个人习惯的做法是：对外发布的 SDK，尽量保证小版本之间二进制兼容。因为很多 App 是动态链接的，用户设备上的 App 不会像测试环境那样每次都重新编译。你不保证二进制兼容，就等于让用户在不知情的情况下用着有问题的 App。
2.5 知识结构图：四种兼容性的关系与影响范围
我画了一张图，用来总结这一章的核心逻辑。你可以把它当作“兼容性诊断路线图”：
2.6 实践中的兼容性策略
有了理论，还得落地。我总结了自己的三点经验：
- 用自动化工具做二进制兼容性检查：ABI Compliance Checker、Google's abi-dumper 这些工具可以帮你对比两个版本的符号表、结构体布局、虚函数表变化。别全靠肉眼。
- 在 CI 中加入兼容性测试：不仅仅是编译通过，还要用旧版编译好的二进制文件去链接新版 SDK，跑一遍功能测试。特别是动态库场景。
- 区分公共接口与内部实现：只有公开头文件里的内容才算契约。内部的
detail命名空间、private方法、impl结构体，都不应该被外部直接依赖。我见过有人把内部类放在公开头文件里，结果一改 ABI 就崩了。
一句话总结：
- 改源码，先问自己：“影响编译吗？”——源码兼容
- 再问自己：“影响链接和加载吗？”——二进制兼容
- 最后问自己：“运行时行为变了吗？”——行为兼容
嗯，这一章的内容就到这。理解了兼容性的本质，后面讲具体测试方法时你就知道该测什么、怎么测了。