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

Question

关于后端实现的逻辑，我想确定什么可能被认为是 API 的 URI 版本控制的最佳实践。

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

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

一段时间后，我们需要向用户 API 添加另外两个必填字段：

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

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

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

如果这两个新字段“年龄”和“地址”不是强制性的，这不会被视为重大变化，但既然是，我认为有几个选择：

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

如果我只对所有用户 API 版本使用一个管理器并在其中放置一些约束/验证，则 V2 将起作用，但 V1 将抛出异常，因为这些字段不存在。

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

Answer 1

您认为 API 版本控制是一个有争议的问题，这是正确的。您还进行了重大更改，因此增加 API 的版本是正确的决定（wrt semver）。

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

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

希望这个模型将有助于保持代码整洁：master存储库中的分支只需要处理最新的 API。如果您需要对较旧的 API 版本进行更改，这可以相对轻松地完成：分支提交V1，进行更改，然后将HEAD修改后的分支定义为 'new' V1。

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

希望这个解释是有道理的；但如果没有任何问题，请发送给我！