web-services - Web 服务 API 版本控制

Question

我为我的客户提供了一个小型 Web 服务 API，我计划随着时间的推移对其进行改进。所以我需要某种版本控制，但我找不到有关您如何执行此类操作的任何信息。

有最佳实践吗？

如何在不破坏与 Web 服务使用者的兼容性的情况下不断添加新功能？

Answer 1

版本控制是一个复杂的主题，因此首先，您需要以更具描述性的方式定义您的目标。可以说您有一个界面可以确保您永远不会破坏兼容性，但根据新功能是什么，这甚至可能是不可能的。所以有不同的情况和不同的取舍。

如果您的意图是仅向新消费者提供新功能，并且您的所有消费者都是直接消费者(没有中介、框架等)，那么离散端点方法是最佳选择。每次添加一个有中断风险的功能时，创建一个新的端点，给它一个新的版本号，然后让消费者知道要验证它并切换他们的配置。这种策略是经过验证的，也是正确的，但它的缺点是给消费者带来了跟上时代的负担。此外，如果服务之间存在依赖关系，则跟踪它可能会成为一件苦差事。好处是，如果代码中断，这不是(直接)你的错。

另一个主要策略是可扩展接口(interface)。我知道这里有三种不同的品种。首先，是一种接口(interface)类型，它试图很好地描述服务域，以至于在给定现有接口(interface)的情况下，您可能添加的每一个可能的功能都是可能的。如果这听起来很难，那就是。您可以称其为完美的界面。一切都被完整地描述了，但整个域也被完整地描述了。然而，“完美”实际上只是在纸上。

第二种是看起来像普通接口(interface)但添加了通用扩展点的类型。在 WSDL 中，这意味着 xs:any、名称-值对或类似的东西。您可以将其称为基本的可扩展接口(interface)。做起来并不难，但也不是没有并发症。扩展点可能会使接口(interface)在某些工具(xs:any)中更难使用，或者显式地失去一些验证输入和输出(名称-值对)的能力。滥用这些扩展点也很容易使版本 3 或 4 很难使用。

第三种是将您的接口(interface)转换为字节流的类型。你可以称这些为上帝接口(interface)。他们并非没有理由，但如果您正在使用其中一个，您可能想问一下您为什么要使用 Web 服务。也许您应该考虑原始 TCP/IP 或基本 HTTP GET/POST。但也许您已经厌倦了 WSDL 和 XSD 的复杂性，只想从头开始，但由于某些基础设施的原因，您与 Web 服务相关联。但是要意识到，一旦您开始走这条路，您将需要一种全新的方式来向您的消费者描述如何/不使用您的服务，如果您为此使用 XSD.. 好吧，您基本上回到了哪里你开始了。

您最好的选择是了解所有这些选项并通过首先尝试“完美界面”来处理您的服务设计，然后放弃并添加通用可扩展点。尝试设计完美的界面将迫使您学习可以使您的服务更好的东西，而不仅仅是您的界面，但这需要时间，如果您不以某种方式限制时间，那将需要永远。

有点少了一个真神接口(interface)，还有包装接口(interface)。如果你的系统有层，你希望你的界面也有层。当您更改 B 层时，您只想更改 B 层，而不是 C 层中的所有实例。