一下文章内容来自之前做API接口时整理的一些内容，记录分享一下。

在HTTP和HTML发展的早期，有着这样一条规则：任何浏览器在遇到无法识别的元素或元素属性时，都应该像该标签不存在一样行事。这使得快速更新HTML的功能成为可能，而不会增加HTML客户端应用程序（浏览器）的 "可破坏性"。(注：参见Bert Bos 2001年关于"W3C、XML和标准化"的演讲，以了解早期HTTP/HTML设计的一些情况。)

所有类似例子都可以追溯到指导大多数互联网标准本身创建的一个基本规则。Jon Postel在1980年提出的"稳健性原则"：

"在你所做的事情上要保守，在你接受别人的东西上要自由"。

正确管理API的长期变化的第一条规则是不要把破坏性的变化提交给生产。原因很简单：一旦你发布了你的API，人们开始使用它，这个界面就是一个承诺。而打破这一承诺可能意味着失去客户。正如亚马逊的Werner Vogels所说的那样："API是永远的"。他在2016年的一篇博文中说、 

"[在亚马逊] 我们知道，设计API是一项非常重要的任务，因为我们只有一次机会来做好它。"

 

API接口向后兼容的3个规则

有一些简单的实施规则，你可以用来减少在你的API生态系统中引入破坏性变化的可能性。如果你想长期成功地管理API，将这些作为你的API设计和审查实践的一部分是非常重要的。

规则一：不要拿走任何东西。

第一条规则是，一旦你发布了一个API，你就不能从它那里拿走东西。你不能拿走一个承诺的URL，一个输入参数，或一个输出数据点。即使你在文档中告诉 开发者你的API的某些元素可能会消失或改变，你仍然不能这样做。因为，嗯，开发人员。

这第一条规则的真相在被称为 "海勒姆法则"或 "隐性依赖法则 "的东西中得到了解释：

"如果有足够数量的API用户，你在合同中承诺什么并不重要： 你的系统的所有可观察到的行为都会被某人所依赖。"- Hyrum Wright，谷歌的员工软件工程师。

这也适用于枚举值。如果你有一个名为status的字段，并记录了它有五个可能的值，你就不能在以后发布API的更新时，status只有四个可能的值。

规则二：不要改变任何东西的含义。

第二条规则指出，你不能改变你的API中现有元素的含义。如果你承诺过滤器语句中的count参数是指 "用户数"，那么你以后就不能把同一个参数改为 "页面数"。

改变事物的含义与拿走它并以其他东西取代它的效果相同。那是一种破坏性的改变，也是你对API的希波克拉底誓言的放弃。

规则三：所有的新增功能都是可选的。

第三条规则是，任何新的功能（URL、输入参数和输出参数）都必须被视为可选。如果你的addCustomer操作在最初的版本中采取了四个必要的参数，你就不能增加一个新的、第五个必要的参数。同样，这实质上是拿走了旧的addCustomer方法，而用一个非向后兼容的addCustomer版本来代替它。

当然，在有些情况下，你别无选择，只能引入一个突破性的变化。也许你的团队搞砸了，API泄露了个人身份信息，或者一些法规发生了变化，你不再被允许接受或分享数据，等等。当这种情况发生时，是时候拿出你的分叉了。因为一个API的新 "版本 "实际上只是一个致命的分叉（用软件术语说）。

分叉是软件工程中一个相当著名的术语。它可以追溯到20世纪80年代初通过Usenet的在线讨论，指的是在一个项目的主干上创建一个分支。当时的假设是，一旦你从你的分叉处分支，你就不会再期望合并到主干上了。虽然我们今天在软件工程中经常使用主干、分支和合并，但API往往会随着时间的推移而 "保持分叉"，很少再合并到一起。

如果你知道你需要引入一个突破性的变化，分叉你的API并在一个新的URL空间中发布它。如果你愿意，可以称之为 "版本"。但你仍然不是詹姆斯-邦德，所以要注意，发布新版本并不意味着你可以杀死旧版本。相反，你需要将它们并排运行一段时间。这就避免了我们前面提到的整个 "中指 "的情况。

有了并排的API，API消费者可以继续使用他们当前的API版本，直到他们准备好在未来的某个时间点进行升级--这是他们自己的时间表，而不是你的。

Salesforce是一家非常了解如何分叉API以获得乐趣和利润的公司。他们有一个习惯，每年发布三次新版API。他们2021年春季的API是51版。我最后一次检查显示，他们支持所有以前的版本，可以追溯到2014年春季（也就是v30！）。是的，Salesforce支持20个过去的版本，并排在一起。

开源冠军Eric S. Raymond将 "分叉 "与悲惨或代价高昂的事件联系起来。创建软件分叉通常表明存在无法解决的分裂，并意味着大量的重复工作。而且，正如我们在Salesforce模式中看到的那样，在API领域也是如此。

如果你致力于发布突破性的变化，你也需要致力于并排发布、文档、在线支持，等等。