如何确保自己维护的库/软件包符合向后兼容性要求

一、基础规则约束 #

• 严格遵循语义化版本（SemVer）规范：不兼容的API变更必须提升主版本号，新增向下兼容的功能提升次版本号，问题修复提升修订号。.Net 生态建议显式声明程序集的 AssemblyVersion 与 AssemblyInformationalVersion，区分程序集绑定版本和发行版本，避免版本号变动导致的依赖绑定失败。
• 公开API修改强制遵循兼容规则：所有对外暴露的类、方法、属性、枚举值，只要属于用户可调用的公开范围，不允许直接修改签名、删除、调整参数默认值。如需给方法新增参数，必须保留原有签名的重载方法，不得直接修改原方法的参数列表。例如原有方法为 public void GetUser(int userId)，新增参数时应额外实现 public void GetUser(int userId, bool includeDeleted)，原方法保持不动。
• .Net 生态可通过 [Obsolete] 特性标记计划废弃的API，至少保留2~3个次版本周期后再删除，特性说明中需明确标注替代方案，方便用户逐步迁移。
• 序列化相关结构禁止随意调整：JSON/XML序列化字段名、枚举的基础数值、数据传输对象的属性顺序等内容的调整，即使方法签名不变也会导致隐性兼容性问题；新增序列化字段必须设置默认值，不得要求用户侧强制传值。

二、自动化测试方案（必须部署，仅靠代码评审无法覆盖所有兼容性问题） #

代码评审仅能识别明显的API变更，隐性的兼容性破坏（如方法返回值隐式类型调整、参数默认值修改、序列化结构变化、依赖版本冲突）极易漏过，自动化测试是必须的保障手段，核心测试类型如下：

2.1 API签名兼容性测试 #

• .Net 生态可使用 Microsoft.CodeAnalysis.PublicApiAnalyzers Roslyn 分析器，工具会自动跟踪项目的公开API签名生成快照文件，当公开API发生不符合规范的变更时直接阻断构建，API变更的内容会直接体现在快照文件的diff中，评审阶段可快速识别。
• 通用生态可使用对应语言的API对比工具：Java生态用japicmp，JS/TS生态用api-extractor，工具会自动对比当前版本与上一个稳定版本的API差异，不兼容的变更直接终止构建流程。

2.2 行为兼容性测试 #

• 覆盖所有公开API的回归测试用例，每次构建全量运行，确保已有API的输入输出、异常表现与之前版本完全一致。
• 可增加版本对比测试逻辑：将相同输入分别传入旧稳定版本和当前开发版本的库，自动对比输出结果，不一致时触发告警。

2.3 集成兼容性测试 #

• 模拟用户真实集成场景：.Net 生态需覆盖不同框架版本（.NET Framework 4.8、.NET 6、.NET 8等）、不同NuGet安装模式（PackageReference、packages.config）的安装、编译、运行测试，排查依赖冲突、绑定重定向错误等问题。
• 针对支持的所有包管理器的安装、引用场景都要做覆盖测试，避免包打包规则错误导致的兼容性问题。

三、代码评审补充规则 #

在自动化测试的基础上，代码评审需增加对应的检查项，补足自动化覆盖不到的场景：

• 所有公开API的变更必须单独标注，评审人需确认变更符合兼容性规则，已提供对应的兼容方案（如重载、废弃提示）。
• 涉及序列化、IO输出、外部协议交互的代码变更，必须评估对用户侧原有逻辑的影响。
• 主版本迭代以外的版本发布，禁止出现任何公开API删除、签名修改的操作，修复严重安全漏洞需做破坏性变更的除外，且必须提前至少3个版本公示。

内容的提问来源于stack exchange，提问作者LostInComputer