API 向后兼容性的最佳实践 [英] Best practices for API backwards compatibility

问题描述

我正在开发与 JSON API 通信的 iPhone/iPad/Android 应用.

I'm working on an iPhone/iPad/Android app which communicates with a JSON API.

应用程序版本的第一个版本已完成，现在正在进行其他开发阶段.在附加阶段，应用程序需要与新版本的 API 集成，并允许用户访问附加功能，例如新屏幕或现有屏幕中的修改行为.但是，该应用确实需要落后于以前版本的 API.

The first release of the version of the app is complete, and now additional phases of development are taking place. In the additional phases, the app needs to integrate with a new version of the API and allow the user access to additional features such as new screens or modified behaviour within existing screens. The app does however need to be backwards with previous versions of the API.

处理此类要求的最佳做法是什么?我可以在整个代码中进行检查:

What is the best practice for tackling such a requirement? I could of could do checks throughout the code:

if (APIVersion == 1) {

} else if (APIVersion == 2) {

} else if (APIVersion == ....) {

}...

但我担心这种方法的可扩展性.我想到了工厂方法，但我不确定这会让我走多远.

But I'm concerned about the scalability of this approach. The factory method comes to mind but I'm not sure how far this would get me.

谢谢，标记

推荐答案

发布新的 API 版本是非常罕见的事情.通常，您只需添加新的可选参数或新方法即可实现向后兼容.例如，如果你有一个名为 search 的方法，但现在你对它的工作方式不满意，你可以通过多种方式来处理它:

Release of a new API version is a very rare thing. Usually you can achieve backward-compatibility just by adding new optional parameters or new methods. For example, if you had method named search, but now you are dissatisfied with the way it works, you may deal with it in various ways:

• 如果更改很简单，您可以添加一个新的 mode 参数，该参数默认为 mode1(因此它向后兼容).如果用户提供 mode2，您可以按照您自己的建议使用适当的 if 条件检测它.(此外，通常您可以想到比模式"更好的名称.)

• If the change is simple you may add a new mode parameter which defaults to mode1 (so it's backward-compatible). If user supplies mode2 you detect it with a proper if condition as you proposed yourself. (Also, usually you can think of a better name than "mode".)

如果变化很大，您可以添加一个使用新界面的新 search2 服务.然后将 search 方法标记为已弃用(但仍然有效且向后兼容).通常当你这样做时，你可以重构你的代码，几乎所有的逻辑都在search2方法中，而你的旧search 方法使用修改后的参数在内部调用 search2 (并适当地重新格式化结果).如果您正确地执行此操作，您将不再需要更改 search 方法.当您更改表格等时 - 您只需要修改 search2.

If the change is a big one, you may add a new search2 service which uses the new interface. Then you mark search method as deprecated (but still working and backward-compatible). Usually when you do this, you can refactor your code in such a way, that almost all of the logic is inside the search2 method, and your old search method calls search2 internally with modified parameters (and re-formats the results appropriately). If you do this properly, you won't ever need to change search method anymore. When you alter your tables etc. - you will only need to modify search2.

我的观点是，避免发布 API 的 N+1-st 版本.如此大的发布意味着您的所有方法发生重大变化，而不仅仅是一种.许多主要 API 从未发布其 API 的第 2 版，它们仍然使用第 1 版，只是对其中的部分进行了轻微修改，如上例所示.

My point is, avoid releasing N+1-st version of an API. Such big release implies major changes in ALL of your methods, not just one. Many major APIs never released version 2 of their API, they still use version 1, just slightly modify portions of it, as in the example above.

如果您绝对确定要发布 N+1-st 版本的 API，请为您的所有方法创建新的入口点.如果您有一个名为 services 的文件夹，请创建一个名为 services-v2 的新文件夹.重构您的 services 代码，使其充分利用 services-v2.如果您认为这太过分了，那么我认为您还不需要 N+1-st 版本的 API.

If you are absolutely sure about releasing N+1-st version of you API, create new entry points for ALL of your methods. If you had a folder named services, create new one named services-v2. Refactor your services code so that it uses the most of services-v2. If you think it's overkill, then I think you don't need N+1-st version of your API yet.

顺便说一句，不要将集中式 API(如 Google Maps)与分布式 API(如 Android)混淆.Android 一直在发布新的 API 版本，因为有数十亿台 Android 服务器(每个 Android 设备是一个)，而且它们都不能简单地由 Google 远程升级.下一版本的 Android 仍然向后兼容上一个版本，增加数字只是为了表示新功能.您仍然可以在 Android 7.0 上运行为 Android 3.0 构建的应用程序(用户可能会收到一些额外的警告，但应用程序会运行).Android 应用程序开发人员使用这些数字来描述其应用程序的最低要求".然而，集中式 API 通常会增加它们的版本号以指示重大的向后不兼容更改.

BTW, do not confuse centralized APIs (like Google Maps) with distributed ones (like Android). Android releases new API versions all the time, because there are billions of Android servers (each Android device is one), and they all cannot be simply upgraded remotely by Google. The next version of Android is still backward-compatible with the previous one, the number is increased only to indicate new features. E.g. You can still run apps built for Android 3.0 on Android 7.0 (the user might get some extra warnings, but the app will run). Android-app developers use these numbers in order to describe "minimum requirements" for their apps. Whereas, centralized APIs usually increase their version number to indicate a major backward-incompatible change.

这篇关于API 向后兼容性的最佳实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！