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