Restful服务应不应该在URI中加入版本号

程序员们对于Restful服务应不应该在URI中加入版本信息的问题在stackoverflow上进行了积极的讨论: Best practices for API versioning ,该问题被赞了720次–很少有被赞这么多次的问题。

支持在URI中加入版本信息的一方认为：

1. 保持接口的向后兼容是一件十分困难或者说费精力的事情，而在URI中加入版本信息则避免了向后兼容，另外通过过期提示，重定向，文档等手段也能降低用户迁移到新的接口上的成本。

反对在URI中加入版本信息的一方认为：

1. 不同API版本支持的资源类型是不一样的，当用户从一个版本切换到另外一个版本时原有的代码很有可能不能正常工作，这无疑加大了用户迁移的成本。

2. Restful服务中的URI对应着相应的资源，用户在请求某个URL时他们期望得到的是某个资源，而版本和资源的概念没有任何关系，因此在URI中加入版本会让用户混淆。（另外版本也不应用来指定资源的表现形式，例如json,xml）

3. 版本的加入会让整个Restful服务变得混乱，除非重写整个服务，否则你就会经常碰到这样的情况：一些低版本的资源指向了一些高版本的资源，如果不修改前者，那么很可能新的客户端代码会出错，如果修改前者，很可能旧的客户端代码会出错。

我个人觉得，是否要加版本号，要根据具体情况。

如果，你开发的这套restful接口仅有自己team或者有限的几个team调用，那么就可以考虑不加版本号，都是自己team的，当你要更新的时候，通知下其他team的人就好，其他team看下你这次更新是否影响，以决定是否调整，以前的代码调用逻辑，这种情况下版本号意义不大，你可以不加；

如果，你开发的restful接口是开放的，你也不知道都有谁调用过，那么这个时候版本号就是必须的了。以百度地图接口为例，百度发布了restful风格的地图接口在网上，全国甚至全世界各行各业都可以调用这些接口，百度要对接口进行升级，该怎么办？如果百度直接在原有的url上进行升级，会产生什么样的结果呢？不可预估。程序员：老板，咱们的产品崩溃了！老板：为啥？程序员：百度升级了接口！哪怕仅仅是多返回了一个字段，都可能导致调用者原有的代码出现问题，毕竟百度无法知道所有人都是怎么解析返回值的。这个时候最好的做法就是加版本号，保持原有版本，发布新的版本，所有问题迎刃而解。老用户也不用因为百度的升级，进行代码的更新，新用户又能享受最新的接口，完美。

总结下，判断是否要加版本号的方法：

1.是否明确的知道都有谁调用了你的接口，并且能通知到，如果能，那可以不加版本号；

2. restful接口升级的时候，原有版本是否保留，如果不保留，可以不加版本号；

如果你还是判读不了，或者不想做判断，那就加上版本号，加上肯定是没有问题的。

当然加版本号也是有技巧的，并不是api/v1/user这样加，这样加肯定是不行的，我们的restful接口多数情况下是包含多个功能模块的，如果其中有一个接口需要升级，而其他接口都不变动，你的url该怎么改呢？api/v2/user?那其他接口呢？还是api/v1/...这就会很混乱，别人调的时候就想怎么又有v1又有v2的，我到底是用v1还是v2?

版本号应该放在一个功能模块的后面，甚至一个url就应该自己独立的版本，如api/user/v2，这样调用者就不会有整套接口都升级到v2的错觉，可能有人会说restful的url是一个资源，这样不太合适，其实你可以理解为用户两个版本的资源嘛，用户资源下的两个不同的版本，由于我这两个user资源同时存在，我当然要标识两个资源的不同，我觉得还能说的通。

我们什么时候发布新版呢？并不是一有什么修改就要算一个版本，我觉得当接口输入输出参数变化时才能算一个新版本