9

在公开不同的 API 版本时，您如何处理存储和检索可能具有不同结构的数据？

假设我们有两个 API 版本；V1 和 V2。V1 和 V2 都有一个位于“ https://api.com/message ”的 POST 端点，它将根据传递的数据在数据库中创建一条消息，例如：

{
    DOB: '2014-12-01'
}

在 V1 中，所需的数据与 V2 不同，因为在 V2 中，我们决定将 DOB 从格式为“YYYY-MM-DD”的字符串更改为整数时间戳，例如 1284723728323

在这种情况下，当我们从使用 V2 API 的调用中保存数据时，DOB 字段将是一个整数，但从对 V1 的调用中保存时，它将是一个格式非常不同的字符串。

随着 API 的每次迭代，我们可能会修改底层数据的许多方面。调用较旧的 API 版本将导致存储的数据对于其他版本的 API 不正确。

是否有一种优雅的方式来处理需要不同格式/结构的数据的不同 API 版本？

4

2 回答 2

6

我首先要做的是确保每个面向 Web 的 API 对应interface于真实编程语言（例如 Java）中的实际 API。

所以，这个问题现在变成了编程语言 API 版本控制的问题，并且没有特定于 Web 服务的考虑。

然后，我会让接口的名称包含版本号，如 MyWebServiceInterfaceV1。

一旦接口的一个版本发布到外部世界，（可以这么说，“它在野外是免费的”）包含该接口的源代码文件夹被锁定在源代码存储库中，因此没有人可以再次修改它， 曾经。然后你制作一个接口的副本并增加它的版本号，从那一刻起，所有的新工作都在新版本上完成。

所以，我们现在正在开发 MyWebServiceInterfaceV2。

对于您引入的每个新版本的接口，您还编写了一个转换器类，它实现了旧接口并映射到新接口，并且您继续维护该类，直到新接口也被锁定。

因此，从 V1 到 V2 的转换器类必须能够将字符串日期转换为整数日期，也可能反过来：整数日期到字符串日期。这里要意识到的重要一点是所有转换都应该是可能的；如果似乎不可能进行转换，那么这意味着您计划在一个方向上进行更改，这将使您的系统不向后兼容旧版本。只要您在所有新设计中牢记向后兼容性，所有必要的转换都应该保持可能。

如果您有 N 个版本，您可以实现 (N-squared)/2 个不同的转换器，以便能够直接从任何版本转换到任何较新的版本，或者您可以只有 N 个转换器，每个转换器只能转换在两个连续版本之间，并根据需要堆叠尽可能多的版本，以便逐步从非常旧的版本升级到最新版本。

当然，在任何给定时间，只有最新版本的接口由与实际数据库通信的实际实现支持。

于 2015-02-09T15:04:15.750 回答
4

API 版本接受的表示不应与数据在后端的存储方式相关。我会这样做：

  • API 的 V1接受并生成 YYYY-MM-DD 字符串作为日期。
  • API 的 V2接受并生成 1284723728323 整数作为日期。
  • 两个版本的 API 将它们的格式映射到和从一个通用的存储类型。
  • 如果必须更改公共存储类型（例如从字符串到 int），则会执行内容迁移以及映射代码的任何必要更新。
于 2015-02-09T14:59:32.040 回答