开发API：新功能和向后兼容性之间的平衡
我现在正在开发我们产品的开发人员 API 功能。
第一个版本已发布，目前用户数量较少。 自从我开始开发它的第二个版本以来，一些部分被重新设计，一些部分被删除，以使API更加优雅和清晰。
但第二版本的部署对于旧版本用户来说可能会很痛苦。 我们的营销部门正计划大幅增强我们的 API 产品，为其添加更多功能。
我应该如何构建系统，那么
1)我们不会受限于“旧版本”来添加新的有趣功能
2)当前的API用户不会因为需要重新设计他们的系统以符合更改后的API而不满意
，或者API产品应该在沙箱中进行相当长一段时间的测试在公开发布之前，所以规范中不会有任何重大修改？
I'm working now on an API for developers feature of our product.
The first version was released and it has small number of users at the moment. Since I started to develop its second version, some parts were reworked, some parts were removed to make the API more elegant and clear.
But the 2nd version deployment can be a pain for old version users.
Our marketing department is planning to enhance our API product a lot, add more features to it.
How should I build the system, so
1) we wouldn't be constrained to the "old version" to add new interesting features
2) current API users won't be dissatisfied because of the need to rework their systems in order to comply with the changed API
Or should the API products be tested in a sandbox for quite a long period of time before the public release, so there wouldn't be any significant modifications in the specification?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（5）
当您必须对已有一些用户的 API 进行更改时，最好的方法可能是弃用旧的 API 调用并鼓励使用新的调用。
删除旧 API 调用的功能可能会破坏旧代码的功能，因此这可能会导致一些使用“旧”API 的开发人员感到有些不满意。
如果您的语言提供了指示某些功能已被弃用的方法，则可以指示用户停止使用旧的 API 调用并过渡到新的调用。 在 Java 中，
@ deprecatedjavadoc 标记 可以在文档中提供注释，说明某个功能已被弃用，或者从 Java 5 开始@Deprecated注释 可用于在调用已弃用的 API 功能时引发编译时警告。此外，提供一些有关从旧 API 迁移到新 API 的技巧和提示，以鼓励人们使用与 API 交互的新方式可能是个好主意。 有了关于该做什么和不该做什么的示例和示例代码，API 的用户将能够根据新的首选方式编写代码。
更改公共 API 将会很困难，但在从旧 API 到新 API 的过渡过程中小心谨慎，我相信可以在一定程度上减轻 API 用户所承受的痛苦。
这是一篇关于如何以及何时弃用 API 的文章 来自 Sun，它可能会提供有关何时适合弃用部分 API 的更多信息。
另外，感谢 David Schmitt，他补充说
Obsolete< .NET 中的 /code> 属性类似于 Java 中的@Deprecated注释。 （不幸的是，编辑被我的编辑覆盖，因为我们都在同时编辑这个答案。）When you have to make changes to the API which already has some users, probably the best route is to deprecate the old API calls and encourage use of the new calls.
Removing the capability of the old API calls would probably break the functionality of old code, so that is probably going to cause some developers using your "old" API to become somewhat dissatisfied.
If your language provides ways to indicate that certain functionality has been deprecated, it can serve as a indication for the users to stop using old API calls and transition to new calls instead. In Java, the
@deprecatedjavadoc tag can provide notes in the documentation that a feature has been deprecated, or from Java 5 the@Deprecatedannotation can be used to raise compile-time warnings on calls to deprecated APIs features.Also, it would probably be a good idea to provide some tips and hints on migrating from the old API to the new API to encourage people to use the new way of interacting with the API. Having examples and sample code on what to do and what not to do, the users of the API would be able to write code according to the new, preferred way.
It's going to be difficult to change a public API, but with some care taken in the transition from the old to new, I believe that it the amount of pain inflicted on the users of the API can be mitigated to a certain extent.
Here's an article on How and When to Deprecate APIs from Sun, which might provide some more information on when it would be appropriate to deprecate parts of APIs.
Also, thank you to David Schmitt who added that the
Obsoleteattribute in .NET is similar to the@Deprecatedannotation in Java. (Unfortunately the edit was overwritten by my edit, as we were both editing this answer at the same time.)微软以其疯狂的向后兼容性而闻名。 他们所做的一件事就是保留所有旧的过时的调用，然后添加新的调用，新程序可以使用这些新的调用来访问旧 API 中无法使用的增强功能。
您没有指定使用哪种编程语言，但 .NET 和 Java 都有一种机制将某些 API 调用标记为过时。 如果向后兼容性对您来说非常重要，您可能想采取相同的路线。
Microsoft is pretty famous for their insane backwards compatibility. One of the things they did was to keep all the old obsolete calls, and then add new ones that new programs could use to access the enhanced features that they could not work into the old API.
You did not specify which programming language you use, but both .NET and Java has a mechanism to mark certain API calls as obsolete. If backward compatibility is very important for you, you might want to take the same route.
这是您必须与社区达成的平衡：
将旧函数保留很久，您最终将获得 Win32 API（30000 个公共
函数）？
不断重写 API，您可以获得类似于 .NET 的东西，其中经常会出现新的修订版（1.0、2.0、3.0、3.5...）并破坏现有程序或引入新的和改进的程序执行 UI 的方式等）
如果社区能够容忍变化并愿意尝试，您将努力获得精益、最新的 API，并知道会导致一些破坏，也称为有点腐烂。 另一方面，如果社区拥有大量遗留代码，并且没有资源或希望将其升级到最新版本，则您必须保持向后兼容性，否则他们的所有内容将无法在新 API 上运行。
请注意其他答案之一：弃用 API 是指示哪些函数“即将淘汰”的常用方法，但只要它们有效，许多开发人员甚至会在新代码中使用它们，因为这些是函数他们已经习惯了。 很少有开明的开发人员既意识到真正注意“已弃用”警告，又花时间在代码中搜索旧 API 的其他实例并更新它们。
It's a balance you will have to strike with your community:
Keep old functions for aeons and you'll end up with the Win32 API (30000 public
functions)?
Rewrite the API all the time, and you can get something similar to .NET, where a new revision goes out every so often (1.0, 2.0, 3.0, 3.5...) and breaks existing programs or introduces new and improved ways of doing UIs etc.)
If the community is tolerant of change and open to experimenting, you will strive for a lean, current API and know that some breakage, aka bit rot, will result. If, on the other hand, the community has tons of legacy code and no resources or desire to bring it up to the latest version, you must keep backward compatibility or all of their stuff will simply not work on the new API.
Note to one of the other answers: deprecating APIs is an often-used way of indicating which functions are "on the way out", but as long as they work, many developers will use them even in the new code because those are the functions they are used to. There are very few enlightened developers that have both the awareness to actually heed "Deprecated" warnings and the time to search the code for other instances of the old API and update them.
向后兼容性应该是默认的。 您应该妥协这一原则的唯一原因是 API 在某种程度上不安全，迫使用户更改为更安全的方法。
Backward compatibility should be the default. The only reason you should compromise this principle is when the API is somehow insecure which forces users to change to more secure methods.
理想情况下，写入原始 API 的应用程序将继续适用于新版本。
添加新功能同时确保旧应用程序继续运行的一种方法是使用两个版本的 API 调用。
例如，假设您当前有一个函数 Foo，它在 API 中采用 2 个参数（参数），但您决定新版本实际上应该采用 3 个参数。 保持 Foo 不变，并添加一个带有 3 个参数的新函数 Foo2。
这样，用户可以继续针对 Foo 进行编码以实现向后兼容性，或者在需要新功能时使用新的 Foo2 函数。
Microsoft 已将这种技术广泛用于 Windows API。
Idealy applicitations written to your original API will continue to work with the new version.
One way to add new features while at the same time making sure that old applications continue to run is to have two versions of an API call.
For example, suppose you currently have a function Foo that takes 2 parameters (arguments) in the API but you decide the new version really should take 3 parameters. Keep Foo the way it is and add a new function Foo2 which takes 3 parameters.
That way users can continue to code against Foo for backward compatibility or use the new Foo2 function if they require the new features.
This technique has been commonly used bu Microsoft for the Windows APIs.