我现在正在为我们产品的开发人员功能开发 API 。
第一个版本已经发布，目前用户数量很少。自从我开始开发它的第二个版本以来，一些部分被重新设计，一些部分被删除以使 API 更加优雅和清晰。
但是对于旧版本用户来说，第二版部署可能会很痛苦。我们的营销部门正计划大量增强我们的 API 产品，为其添加更多功能。
我应该如何构建系统，所以
1）我们不会受限于“旧版本”来添加新的有趣功能
2）当前的 API 用户不会因为需要重新设计他们的系统以符合要求而感到不满意更改后的 API
或者 API 产品是否应该在公开发布之前在沙盒中测试相当长的一段时间，这样规范就不会有任何重大修改？
当您必须对已经有一些用户的 API 进行更改时，最好的方法可能是弃用旧的 API 调用并鼓励使用新的调用。
删除旧 API 调用的功能可能会破坏旧代码的功能，因此这可能会导致一些使用您的“旧”API 的开发人员变得有些不满意。
如果您的语言提供了指示某些功能已被弃用的方法，它可以作为用户停止使用旧 API 调用并转而使用新调用的指示。在 Java 中，@deprecatedjavadoc 标记可以在文档中提供已弃用功能的注释，或者从 Java 5 开始，@Deprecated注释可用于在调用已弃用的 API 功能时引发编译时警告。
此外，提供一些关于从旧 API 迁移到新 API 的提示和提示可能是一个好主意，以鼓励人们使用与 API 交互的新方式。有了关于做什么和不做什么的示例和示例代码，API 的用户将能够根据新的、首选的方式编写代码。
更改公共 API 将很困难，但在从旧到新的过渡过程中要小心，我相信它可以在一定程度上减轻 API 用户所承受的痛苦。
这是一篇关于如何以及何时从 Sun 弃用 API 的文章，该文章可能会提供更多关于何时适合弃用部分 API 的信息。
另外，感谢 David Schmitt，他补充说 .NET 中的Obsolete属性类似于@DeprecatedJava 中的注解。（不幸的是，编辑被我的编辑覆盖了，因为我们都在同时编辑这个答案。）
这是您必须与您的社区达成的平衡：
将旧函数保留很久，你最终会得到 Win32 API（30000 个公共函数）吗？
一直重写 API，你会得到类似于 .NET 的东西，新版本每隔一段时间就会发布（1.0、2.0、3.0、3.5...）并破坏现有程序或引入新的和改进的做事方式用户界面等）
如果社区能够容忍变化并愿意进行试验，那么您将努力争取精简、最新的 API，并且知道会导致一些损坏，也就是有点腐烂。另一方面，如果社区有大量遗留代码并且没有资源或不希望将其升级到最新版本，那么您必须保持向后兼容性，否则他们的所有东西都无法在新 API 上运行。
请注意其他答案之一：弃用 API 是一种常用的方式来指示哪些函数“即将退出”，但只要它们有效，许多开发人员甚至会在新代码中使用它们，因为这些是函数他们习惯了。很少有开明的开发人员既能意识到实际注意“已弃用”警告，又能有时间在代码中搜索旧 API 的其他实例并更新它们。
微软以其疯狂的向后兼容性而闻名。他们所做的一件事是保留所有旧的过时调用，然后添加新的调用，新程序可以使用这些调用来访问它们无法在旧 API 中使用的增强功能。
您没有指定使用哪种编程语言，但 .NET 和 Java 都具有将某些 API 调用标记为过时的机制。如果向后兼容性对您非常重要，您可能希望采用相同的方法。
向后兼容性应该是默认设置。您应该妥协这一原则的唯一原因是当 API 不安全时，它会迫使用户更改为更安全的方法。
写入原始 API 的理想应用程序将继续与新版本一起使用。
添加新功能同时确保旧应用程序继续运行的一种方法是使用两个版本的 API 调用。
例如，假设您当前有一个函数Foo，它在 API 中采用 2 个参数（参数），但您决定新版本确实应该采用 3 个参数。保持Foo的原样并添加一个新的函数Foo2，它接受 3 个参数。
这样，用户可以继续针对Foo进行编码以实现向后兼容性，或者在需要新功能时使用新的Foo2函数。
这种技术已被 Microsoft 普遍用于 Windows API。