这是一个创建于 2656 天前的主题，其中的信息可能已经有所发展或是发生改变。
http://www.ruanyifeng.com/blog/2011/09/restful 阮一峰认为，版本号应该放在 HTTP 请求头中
https://juejin.im/post/59826a4e518825359c5e72d1 这个认为，API 版本号应该区分
而且 github API，也是 URI 中带有版本号的，难道说 github 的 API 设计的不好？
所以我怀疑 阮一峰这个问题上搞错了。
能分享一些实际的设计 API 的经验吗？谢谢
 |
1
acoldfox 2017-08-14 18:06:46 +08:00
觉得这个各说纷纭，到最后是怎么方便怎么来了，我是在 url 中保留版本号的，比如 v1，v2 是独立的模块，如果版本改动太多，就另起一个新 module 跟以前的区分开，互不干扰
|
 |
2
cuebyte 2017-08-14 18:23:34 +08:00 via Android
也不尽然是方不方便的问题，在后端的设计里，URL 本身就是和 controller 挂钩的，而不同版本需要不同的 controller。所以把版本号放在 URL 里是很自然的一件事。况且也更直观。
|
 |
3
gigantic222 2017-08-14 18:30:10 +08:00 via iPhone
原理都一样啊本质上没区别 可能时常需要 simple request 限制 header 吧
|
 |
4
sampeng 2017-08-14 18:35:25 +08:00
我一般扔 header 里面。干净一点
|
 |
5
danielmiao 2017-08-14 18:40:07 +08:00
习惯放在 url 上
1.调用直观，写文档方便 2.不同版本的相同功能接口，可以在不同的包中使用相同的 url，便于代码管理（ maven 版本和 url 版本关联）。 3.不同版本接口可以分开部署，平滑升级，通过 nginx 简单规则匹配就分派到不同的服务器上。 |
 |
6
lslqtz 2017-08-14 18:40:12 +08:00
不加
等改动的时候加，丢 header 比较麻烦 |
 |
7
leky 2017-08-14 18:41:30 +08:00 via iPhone  1
如果返回数据结构一样，个人觉得版本号在 header 会比较方便，客户端都不用改 api url，其它的倒是没什么可说的
|
 |
8
xiaozizayang 2017-08-14 18:41:57 +08:00 via Android
我一般加路由里面
|
 |
9
Kilerd 2017-08-14 18:49:36 +08:00 via iPhone
无论是对前后端来说，怎样都是一两个语句的事情。
这个真的是怎么方便怎么来 |
 |
10
jarlyyn 2017-08-14 18:52:40 +08:00
放在 url 里。
说请求头的，难道现在 url 不是请求头了么？ 另外， 我不是很喜欢很纯粹的 restful 接口。 |
 |
11
dracarysX 2017-08-14 18:59:32 +08:00
基本就是请求头和 url 两种方案比较流行。
不过个人感觉大多数的 API 设计都是 url 这种方案（很多大厂都是这种），这种设计更加直观，清晰。从开发方面看也是比较舒服的，不需要一直去判断请求头的版本去寻找处理函数。 ps：阮一峰也不一定都是对的。 |
 |
12
lightening 2017-08-14 19:08:14 +08:00
这只是 opinion，有什么对错之分么
|
 |
13
jameshuazhou 2017-08-14 19:23:05 +08:00
两种方式都用过，放 url 中别人更不会犯错，而且放请求头中有些木有经验的还得教他怎么做。
理论上放头中更漂亮些，但实际中还是放 url 省心些。 |
 |
14
sunjourney 2017-08-14 20:36:01 +08:00
放 url 里 get 请求是可以缓存的， 阮老师的文章里错误不少或者在转达别人的观点因此有时候会有讲同一个内容的观点矛盾。
|
 |
15
janxin 2017-08-14 21:01:51 +08:00 via iPhone
放头里最好有 api 网关
|
 |
16
mikulch 2017-08-14 21:11:58 +08:00
要。推荐楼主看看《 web api 的设计与开发》这本书。
|
 |
17
lrh3321 2017-08-14 21:30:14 +08:00
放在 url 里+1
老版的 API 可能和新版的跑在不同的 server 上 |
 |
18
changwei 2017-08-14 21:30:58 +08:00 via Android
看了好多大厂，比如说百度，知乎之类的网站都是版本号放 url 中，这样的话测试或者发起请求都更方便，程序里面不需要额外调用各种修改请求头的 api。
|
 |
19
geelaw 2017-08-14 21:45:03 +08:00
如果你把 URL 看作对象的 view，就很好理解版本号放在 URL 里面的想法。这相当于是张三还是李四来看这个对象，是老人还是年轻人看这个对象的问题。
|
 |
20
sobigfish 2017-08-14 21:53:21 +08:00
放 uri 里是为了兼容性，放 header 里貌似还不好分析跟踪-。-
|
 |
21
zhoulouzi 2017-08-14 22:07:38 +08:00
uri 就不是请求头了吗
|
 |
22
qiyuey 2017-08-14 23:50:43 +08:00
github 不是已经不再使用 restful api 了吗
|
 |
23
ETiV 2017-08-15 03:05:48 +08:00 via iPhone
放头里要多几个字节（ x-api-version 这样），所以不放。
|
 |
24
libook 2017-08-15 09:08:50 +08:00
哪个方便用哪个，看你的架构是什么样的，以及 API 版本差异特点。
版本区分仅限于个别 API 的话就加在 Header 里； 版本区分是普遍的、整体的，就写在 URI 里； 如果版本差异巨大，以至于使用完全不同的服务和集群，就写在域名里。 通常不是做 SaaS 的话 API 版本的维护要求不是特别严格吧，所以也没必要做的冠冕堂皇，我们是每年出 1-2 个大版本，同时维护的版本只有 1-2 个，前端强制升级旧版本会直接抛弃，所以直接用域名区分了，简单有效，而且对云计算服务友好。 |
 |
25
zhangmiaoCHN 2017-08-15 09:53:44 +08:00
Facebook 的码农之前也纠结过这个问题，后来搞了一个 GraphQL 试图改善 RESTful API 的局限
现在 Github API v4 版本已经不再使用 RESTful API 了，改用 GraphQL 去构建 API https://developer.github.com/v4/ |
 |
27
ericgui OP @zhangmiaoCHN V3 和 V4 共存，都能用
|
 |
30
derrickT 2018-09-28 11:39:11 +08:00
1. 在 header 里加 version
2. 在请求里加 version 3. 在 nginx 里根据 version 转发到对应的版本 |
Select Language