开发API：在新功能和后向兼容性之间取得平衡

Question

我现在正在使用我们产品的 API for developers 功能。

第一个版本已经发布，目前用户数量很少。自从我开始开发第二个版本以来，一些部件被重新设计，一些部件被移除以使API更加优雅和清晰。

但是第二版部署对于旧版本用户来说可能是一种痛苦。 我们的营销部门正计划大量增强我们的API产品，并为其添加更多功能。

我应该如何构建系统，所以
   1）我们不会被限制为“旧版本”添加新的有趣功能
   2）当前API用户不会因为需要重新设计系统以符合更改后的API而不满意

或者，在公开发布之前，API产品是否应该在沙盒中进行相当长时间的测试，因此规范中不会有任何重大修改？

Answer 1

当您必须对已经拥有某些用户的API进行更改时，最好的方法是弃用旧的API调用并鼓励使用新的调用。

删除旧API调用的功能可能会破坏旧代码的功能，因此可能会导致一些使用“旧”API的开发人员变得有点不满意。

如果您的语言提供了表明某些功能已弃用的方法，则可以作为用户停止使用旧API调用并转换为新调用的指示。在Java中，@deprecated javadoc tag可以在文档中提供已弃用功能的注释，或者从Java 5中可以使用@Deprecated annotation来调用对已弃用的API功能的调用的编译时警告。

此外，提供一些有关从旧API迁移到新API的提示和提示可能是一个好主意，以鼓励人们使用与API交互的新方式。有关做什么和不做什么的示例和示例代码，API的用户将能够根据新的首选方式编写代码。

改变公共API会很困难，但是在从旧版本到新版本的转换过程中要小心谨慎，我相信在一定程度上可以减轻对API用户造成的痛苦程度

以下是来自Sun的How and When to Deprecate APIs的文章，该文章可能会提供有关何时弃用部分API的更多信息。

另外，感谢David Schmitt，他补充说.NET中的Obsolete attribute类似于Java中的@Deprecated注释。 （不幸的是编辑被我的编辑覆盖了，因为我们都在同时编辑这个答案。）

Answer 2

这是你必须与社区打交道的平衡点：

• 为永久保留旧功能，您最终将使用Win32 API（30000公开 函数）？

• 一直重写API，你可以得到类似于.NET的东西，其中每隔一段时间就会出现一个新版本（1.0,2.0,3.0,3.5 ......），并打破现有程序或介绍新的和改进的UI方式等。）

如果社区容忍变化并且愿意接受实验，那么您将努力寻找精益的，当前的API，并且知道会导致一些破损，即有点腐烂。另一方面，如果社区拥有大量遗留代码，没有资源或希望将其提升到最新版本，那么您必须保持向后兼容性，否则他们的所有内容都无法在新API上运行。

---

请注意其他答案之一：弃用API是一种经常使用的方式，用于指示哪些函数“正在退出”，但只要它们有效，许多开发人员即使在新代码中也会使用它们，因为这些是他们习惯的功能。很少有开明的开发人员能够真正注意到“弃用”警告以及搜索代码以查找旧API的其他实例并更新它们的时间。

Answer 3

微软以其疯狂的向后兼容性而闻名。他们所做的一件事就是保留所有旧的过时调用，然后添加新程序可以用来访问旧API无法使用的增强功能的新调用。

您没有指定使用哪种编程语言，但.NET和Java都有一种机制将某些API调用标记为过时。如果向后兼容性对您非常重要，则可能需要采用相同的路径。

Answer 4

向后兼容性应该是默认值。你应该妥协这个原则的唯一原因是当API在某种程度上不安全时迫使用户改为更安全的方法。

Answer 5

写入原始API的Idealy应用程序将继续使用新版本。

在确保旧应用程序继续运行的同时添加新功能的一种方法是使用两个版本的API调用。

例如，假设您当前有一个函数 Foo ，它在API中有2个参数（参数），但您确定新版本确实需要3个参数。保持 Foo 的方式并添加一个新功能 Foo2 ，它需要3个参数。

这样，用户可以继续针对 Foo 进行编码以实现向后兼容，或者如果需要新功能，则使用新的 Foo2 功能。

这种技术已经被微软用于Windows API。