Web服务API版本控制

Question

我向我的客户提供了一个小型Web服务API,我计划随着时间的推移而发展.所以我需要某种版本控制,但我找不到任何关于你是如何做这样的事情的信息.

有最好的做法吗？

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

Answer 1

版本控制是一个复杂的主题,因此首先,您需要以更具描述性的方式定义目标.很高兴地说你有一个接口可以确保你永远不会破坏兼容性,但是根据新功能的不同,这可能是不可能的.所以有不同的情况和不同的权衡.

如果您的目的是仅向新消费者提供新功能,并且您的所有消费者都是直接消费者(没有中介,框架等),那么离散端点方法是最佳选择.每次添加可能存在中断的功能时,请创建新端点,为其指定新版本号,然后让消费者知道对其进行验证并切换其配置.这种策略非常有效,但它的缺点是让消费者承担更新的负担.此外,如果服务之间存在依赖关系,它可能成为一项需要跟踪的苦差事.如果代码破坏它的好处不是(直接)你的错.

另一个主要策略是可扩展接口.我知道这里有三种不同的品种.首先,是尝试如此好地描述服务域的接口类型,在给定现有接口的情况下,您可能添加的每个可能功能都是可能的.如果这听起来很难,那就是.你可以称之为完美的界面.一切都完全描述,但整个领域也完全被描述."完美"实际上只是纸上谈兵.

第二种类型是看起来像普通接口但添加通用扩展点的类型.在WSDL中,这意味着xs:any,name-value对或类似的东西.您可以将其称为基本可扩展接口.这并不难,但并非没有它的复杂性.扩展点可能使界面更难以在某些工具(xs:any)中使用,或者明显失去一些验证输入和输出(名称 - 值对)的能力.以一种使版本3或4很难使用的方式滥用这些扩展点也很容易.

第三种是将您的接口转换为字节流的类型.你可以称这些神接口.他们并非没有理由,但如果你使用的话,你可能会想问为什么你要使用网络服务.也许您应该考虑原始TCP/IP或基本HTTP GET/POST.但是,您可能厌倦了WSDL和XSD的复杂性,而您只是想从头开始,但出于某些基础设施原因,您需要依赖Web服务.但要意识到,一旦你开始走这条道路,你将需要一种全新的方式向你的消费者描述如何/不使用你的服务,如果你使用XSD那么......你基本上回到了哪里你开始了

您最好的选择是了解所有这些选项并首先尝试"完美界面",然后放弃并添加通用扩展点,从而实现服务设计.试图设计完美的界面将迫使你学习能使你的服务更好的东西,而不仅仅是你的界面,但这需要时间,如果你不以某种方式限制时间,它将需要永远.

有点真正的神界面,有包装界面.如果您的系统有图层,您希望您的界面也在图层中.更改图层B时,您只想更改图层B,而不是图层C中的所有实例.

Answer 2

我见过的最常见的策略是通过将版本标识(通常yyyy/MM[/dd])添加到wsdl中对象的命名空间来对WSDL进行版本控制,即:

targetNamespace="http://schemas.mycompany.com/2010/01/widgets"

这可以在per- type(types/schema)级别或整个WSDL级别(<definitions>1.1或<description>2.0)中完成.

有点过时,但IBM Developer Works的这个链接提供了这种方法的基本原理,特别是当版本需要递增时:

向后版本兼容/不间断更改:

• 添加新操作
• 添加新类型

突破性变化:

• 删除或重命名操作
• 将参数更改为方法
• 更改复杂类型

Answer 3

将“API 版本号”添加为所有 API 中的参数，然后在 Web 服务代码中实施策略模式，其中版本号指示要使用的策略。