Web服务API版本控制 [英] Web Services API Versioning

问题描述

我为我的客户提供了一个小型Web服务API，我计划随着时间的发展.因此，我需要某种形式的版本控制，但是我找不到有关您如何执行类似操作的任何信息.

I offer a small Web Services API to my clients which I plan to evolve over time. So I need some sort of versioning, but I can't find any information about how you do something like that.

有最佳实践吗?

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

How can I keep adding new functionality without breaking compatibility with the web services consumers?

推荐答案

版本化是一个复杂的主题，因此，首先，您需要以更具描述性的方式定义目标.非常高兴地说，您拥有一个接口，以确保您永远不会破坏兼容性，但是根据新功能的不同，这甚至可能无法实现.因此，存在着不同的情况和不同的权衡.

Versioning is a complex topic, so first, you need to define your goals in a more descriptive manner. It would be great to say that you have an interface insures you'll never break compatibility, but depending on what the new functionality is, that might not even be possible. So there are different situations and different trade-offs.

如果您的目的仅是向新使用者提供新功能，而您的所有使用者都是直接使用者(没有中介机构，框架等)，那么离散端点方法是最佳选择.每次添加有可能会中断的功能时，请创建一个新的端点，为其提供新的版本号，然后让使用者知道对其进行验证并切换其配置.这种策略经过了反复尝试，是正确的，但是它具有使消费者负担最新信息的缺点.此外，如果服务之间存在依赖关系，则可能会变得难以跟踪.好处是，如果代码中断，则不是(直接)您的错.

If your intent is to only provide new functionality to new consumers, and all of your consumers are direct consumers (no intermediaries, frameworks, etc.), then a discrete endpoint approach is the best choice. Each time you add a feature that risks a break, create a new endpoint, give it a new version number and then let the consumers know to validate against it and switch their configurations. This strategy is pretty tried and true, but it has the drawbacks of putting the burden on consumers to keep up to date. Also, if there are dependencies between services it can become a chore to track. The upside being if code breaks it's not (directly) your fault.

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

The other main strategy is the extensible interface. There's three different varieties here that I'm aware of. First, is the type of interface that tries to so well describe the service domain that every possible feature you might add is somehow possible given the existing interface. If that sounds hard, it is. You might call this the perfect interface. Everything is completely described, but the entire domain is also completely described. The "perfect" is really only on paper though.

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

The second variety is the type that looks like a normal interface but add generic extension points. In WSDLs this means xs:any, name-value pairs or something similar. You might call this the basic extensible interface. It's not too hard to do, but it's not without it's complications. The extension points may make the interface harder to work with in certain tooling (xs:any), or explicitly lose some of your ability to validate inputs and outputs (name-value pairs). It's also pretty easy to abuse those extension points in a way that makes the version 3 or 4 pretty hard to use.

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

The third variety is the type that converts your interface into a byte-stream. You might call these god interfaces. They aren't without their justifications, but if you're using one, you may want to ask why you're using web-services at all. Maybe you should be thinking about raw TCP/IP, or basic HTTP GET/POST. But maybe you're fed up with the complexity of WSDLs and XSDs and you just want to start from scratch but you're tied to web-services for some infrastructure reason. Realize however that once you start down this path, you're going to need a whole new way of describing to your consumers how to/not to use your service, and if you use XSD for that.. well you're basically back where you started.

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

Your best bet is to know all these options and approach your service design by first trying for the "perfect interface", then giving up and adding generic extensibility points. Trying to design the perfect interface will force you to learn things which will make your service better, not just your interface, but it will take time, and if you don't limit that time somehow, it'll take forever.

有一个真正的上帝接口，那里是包装器接口.如果您的系统具有图层，则也希望您的界面也位于图层中.更改B层时，您只想更改B层，而不是C层中的所有实例.

A little bit short of a true god interface, there is the wrapper interface. If you're system has layers, you want your interface to be in layers too. When you change layer B, you only want to change layer B, not all the instances in layer C.

这篇关于Web服务API版本控制的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！