REST版本控制

Question

我目前在一个基于Java的web应用程序上工作。最近，我们使用Spring创建了一些REST端点。之所以如此，是因为我们开发了一个混合移动应用程序，通过这些端点与我们的主要应用程序集成。

问题是，在未来，我们不太确定如何处理更新。如果我们更新API，例如更改端点方法的方法签名，或者更改作为JSON返回的DTO上的属性，那么如果我们的移动用户正在运行过时版本的移动应用程序，我们就会遇到问题。

我们想要实现的是一些东西，将迫使我们的用户更新应用程序，如果它是过时的。我见过很多这样做的移动应用程序。因此，我们考虑为REST提供一个API版本，然后让移动应用程序检查它使用的版本是否与服务器运行的版本相同，如果没有，则强制用户进行更新。

我们面临的问题是：

1. 我们只有一个版本的服务器在任何时候运行。那么我们该如何安排发布时间呢？如果我们发布了新版本的API和移动应用程序，但是应用程序商店还没有公开发布最新版本，会发生什么情况。然后，用户将被迫做一个更新，但更新的应用程序还没有提供给他们。
2. 如何维护API版本号？在移动应用程序上，我们可以配置它。但是在服务器上，必须维护版本号并不太好。我这么说的原因是，如果我们更改了方法签名或DTO等，而忘记在发布之前手动更新这个版本号，那该怎么办？当然，有一种更自动的方法可以根据API的当前定义生成一些唯一的"API密钥“？然后，我们可以使用它而不是API版本号。

Answer 1

有几件事你可以做。

1. 架构师API版本控制从一开始就开始了。我在REST中看到了两种常见的方法:在所有REST资源端点之前添加一个/v1、/v2等URL前缀，或者使用HTTP头来协商版本。有些宗教战争是正确的。这是你的API。做你认为正确的事。
2. 从源代码中的API端点代码中抽象出业务逻辑。这样，您就可以拥有一个v1和v2端点，它在较低级别的服务层重用公共代码。这是你从出发就不需要做的事。您可以等到API的v2开始分离出来。
3. 根据现有的API版本对每个构建进行自动化测试(以及您正在构建的任何新版本，但回归测试是我要做的重点)。
4. 强制应用程序更新，或者至少通过应用程序版本跟踪使用情况，可以允许您删除/清理任何支持遗留版本的代码。

我正在做一个类似的项目，为一个新的移动应用程序创建一个新的REST。我是按版本划分URL空间，所以是https://api.blahblahblah/v1.0/resource。

目前，我的业务逻辑被嵌入到接受HTTP请求的代码中，因为这种逻辑没有其他用途。然而，当我需要制作一个新版本时，我将重构v1 API代码，将任何不特定于v1的代码分离到一个更可重用的模块中，然后可以重用。

取决于版本在结构上的不同，您可能需要一些冗余来保持API的分离。例如，您可能需要一个通用的UserEntity对象来表示数据库中有关用户的信息，但是需要一个UserV1Resource和UserV2Resource对象，用于带有适配器或其他设计模式的独立版本，以协调被序列化为JSON或XML的不同类型。

通过进行自动化的API测试，我可以根据自己的需要进行任何重构，并在执行过程中分离，因为我知道一旦我破坏了任何向后兼容性，我的测试就会对我大喊大叫。

API目前只供我们的移动应用程序使用的一个好处是，我们只需要担心与支持的应用程序版本的兼容性。如果我们能够确保我们的最终用户定期更新他们的应用程序，我们将能够删除旧版本，这有助于减少我们的技术负担。

Answer 2

听起来你需要对你的API进行向后兼容的更新。

由于您控制着在移动端调用API的客户端代码，所以只需编写应用程序就可以忽略JSON响应中出现的新字段。这将使应用程序变得不那么脆弱，并允许你随意扩展你的对象。充分利用HATEOAS，让客户在对象中导航超链接，而不是硬编码到URL结构中。

您应该开始构建与每个服务器版本兼容测试的文化和流程，这样您就可以自动验证您的旧API客户端(当然是永远在从未更新其应用程序的人的手机上)是否仍能与您为服务器计划的更新一起工作。在语义版本化中，这类似于对API进行小版本升级。

如果您认为您在某个阶段需要进行非常不兼容的API更改，这会破坏您以前的应用程序，那么从一开始就对您的API客户端进行“兼容性检查”。在启动时，他们应该检查服务器上的一个简单API来进行基本版本握手。如果服务器的响应是“我们不能再支持您的旧客户端代码了”，那么就让您的应用程序出错，并给出一条消息，告诉用户从应用程序商店中提取最新版本。但是，由于这是一个相当恶劣的用户体验，最好只是建立在合理的兼容性，从开始。