如何管理API版本控制的逻辑？

Question

bounty到期在6天内。该问题的答案有资格获得+ 50声望赏金。variable想要引起更多关注对此问题。

关于后端实现的逻辑，我想确定API的URI版本控制的最佳做法。

假设我们有一个具有以下API的Java应用程序：

http://.../api/v1/user
Request:    
    {
      "first name": "John",
      "last name": "Doe"
    }

过一会儿，我们需要向用户API再添加2个必填字段：

http://.../api/v2/user
Request:    
    {
      "first name": "John",
      "last name": "Doe",
      "age": 20,
      "address": "Some address"
    }

我们为每个版本使用单独的DTO，一个具有2个字段，另一个具有4个字段。

我们对于应用程序只有一个实体，但是我的问题是，作为最佳实践，我们应该如何处理逻辑？可以只在一项服务中处理吗？

如果这两个新字段“年龄”和“地址”不是必填项，则不会被认为是一项重大更改，但是既然如此，我认为有几种选择：

• 对于所有用户API版本，仅在业务层中使用一个管理器/服务（但是代码的复杂性在于，只有一个管理器会随着时间的推移而增长，并且难以维护）
• 仅对所有用户API版本使用一个管理器，并且还使用一个类作为翻译器，这样我就可以使新版本兼容旧API版本
• 业务层中针对每个用户API版本的新经理/服务

如果所有用户API版本仅使用一个管理器，并在其中进行一些约束/验证，则V2可以运行，但是V1会引发异常，因为这些字段不存在。

我知道版本控制是一个大话题，但直到现在我都无法在网络上找到具体答案。我的直觉说，为所有用户API版本使用一个管理器将导致与干净代码无关的方法，而且，我认为添加新版本的任何更改都必须尽可能松散地耦合，因为使旧方法过时并及时删除它们会更容易。

Answer 1

您相信API的版本控制是一个有争议的问题，这是正确的。您也在进行重大更改，因此增加API版本是正确的决定（w.r.t. semver）。

理想情况下，您的后端代码将受版本控制（例如GitHub）。在这种情况下，您可以放心地将V1视为存储库中的特定提交。这是已部署的代码，正在为V1提供流量。然后，您可以根据需要继续对代码进行更改。在某个时候，您将添加一些新的重大更改，并决定将特定提交标记为V2。然后可以将V2与V1一起部署。当您决定折旧V1时，您可以停止提供流量。

[您需要某种方法来确保仅V1流量流向V1后端，而V2流量流向V2后端。通常，这是通过使用Reverse Proxy完成的；流行的选择包括NGINX和Apache。任何足够的反向代理都将允许您基于路径定向请求，这样，如果请求以/api/v1为前缀，则将该请求重定向到Backend1，如果以/api/v2为前缀，则重定向到Backend2。

希望此模型将有助于保持代码的清洁：存储库中的master分支仅需要处理最新的API。如果需要对较旧的API版本进行更改，则可以相对轻松地完成此操作：分支V1提交，进行更改，然后将该修改后的分支的HEAD定义为“新” V1。

对于您应该注意的这个答案，已经做出了一些关于后端的假设。首先，您的后端可以水平缩放。例如，这意味着，如果您与数据库进行交互，则API的多个版本都可以安全地同时访问数据库。其次，您有足够的资源来部署副本后端。

希望这种解释是有意义的；但是如果没有问题，请发送给我！