关于WEB-API的版本控制方法

说到版本控制，那是深有体会的

做到最烂的方式，就是用VER来做区分，然后硬编码在程序代码里面

接下来，看看别人是怎么看这个版本控制的，转文如下：

 

源于对OpenStack Api版本控制约束问题的探讨，Mark Nottingham在其博客中分析了云中Web API各种版本控制机制。他说，如果将Web上的版本 控制与软件版本控制做比较的话，软件版本控制成熟得多，而且一般来说更易于理解。

开发者们习惯了软件版本控制。譬如，在每次发版时都会推出一个版本号。版本号通常包含主版本号和小版本号，有时也会有诸如包版本号之类的称呼。

这种细粒度的版本标识对开发者和用户都非常有益；这些标识的简洁语义有助于判断兼容性和开发过程中的调试。

他接着说，但是，这样的版本思路不能很好地转化成Web API的版本控制。

使用了前一API版本的用户必须要判断如何用新版API进行工作。虽然他们猜测两个版本间应该是兼容的，但是他们却无法肯定。所以，他们仍然需要重写一堆API。

[……]简单地将软件版本控制的方法用于Web API也抵消了人们使用HTTP时得到的许多价值。如果你非要这么做，还不如使用“愚钝”的RPC协议。

Mark认为，Web API版本控制的主旨是保留与现有用户的兼容性。

一个基本原则是，不能破坏现有用户。他们实现了什么，你无从得知，也无法控制。

他还指出：

[……]Web API的版本控制本质上是非线性的。换言之，当你产生一个新标识符时，你就产生了一个全新的东西，不论它是一个HTTP头、媒体类型标识还是一个URI。你甚至可以用“foo”和“bar”来代替“V1”和“V2”。

他还就如何使用HTTP头的扩展机制实现多种版本控制给出了样例。他倡导通过产品令牌（product tokens）标识并解决实现问题。

他将Web上的版本控制分为两类：表现格式变更和资源变更。

很多人（如 Dave）已经充分讨论过表现格式变更的问题了。它们既简单又复杂得让人恼火。总而言之，不要做向后不兼容的更改，如果非要做，就得改变媒体类型。

Mark认为对资源的变更是一个更为有趣的问题。URI是经历过尝试和测试的大众较接受的版本控制方法。接受度差一点的方法是超媒体（hypermedia ）。

REST迷们研究在Web API中使用HATEOS标识已经有很长时间了，而且Roy也对许多人不知道这一方法表示惋惜。

Mark的文章中也就使用超媒体公布资源元数据的方法给出了示例。客户端可以通过这些元数据以及服务端提供的各自资源模板来生成URI。

这样，你就不再需要为接口生成不同的URI，因为由代理驱动的内容商定能够有效地使用这一入口。

他承认有些人赞同使用HATEOAS，也有些人反对，但是该解决方案带来的扩展性优势能够作为支持它的强有力的论据。

我认为，[译注：HATEOAS]的核心观点是，URI已经用于表示太多东西了——持久标识符、缓存键值、相关性解析、书签等——若再加上版本控制和扩展信息，超负荷使用URI的结果只能使其使用效果更差。通过把这些关注点转移到HATEOAS的链接关系和媒体类型中，你得到的是一个灵活的、拥抱未来的系统，它能够以可控的方式演进，而无需放弃享受HTTP（不考虑REST了）的益处。

这里有作者原始的分析。