关于 Restful API 版本号控制的实现选择

[remember5]

背景

项目基于 SpringBoot,业务迭代较快,常有接口不向下兼容的情况，需要实现多版本的接口

多版本实现方式

Api 版本控制的方式：

1. 域名区分管理，即不同的版本使用不同的域名，v1.api.test.com ，v2.api.test.com
2. 请求 url 路径区分，在同一个域名下使用不同的 url 路径，test.com/api/v1/，test.com/api/v2
3. 请求参数区分，在同一 url 路径下，增加 version=v1 或 v2 等，然后根据不同的版本，选择执行不同的方法。

实际项目中，一般选择第二种：请求 url 路径区分。因为第二种既能保证水平扩展，有不影响以前的老版本

原文链接： https://blog.csdn.net/weixin_39255905/article/details/110391515

两种实现对比

比较倾向 url 路径区分，如上实现@ApiVersion()

如：test.com/api/v1/test 其中v1是版本 test是具体接口

基于 Controller 隔离控制

在 Contorller 层添加注解，如 @ApiVersion(1) 和 @ApiVersion(2)

• 请求正确的版本地址，会自动匹配版本的对应接口
• 请求的版本大于当前最大版本时，默认匹配当前最大版本。
• 请求的版本小于当前最小版本时，会 404
• 请求对应的版本不存在接口(methods)时，会匹配之前版本的接口

基于 Methods 中的注解大小控制

在具体的 Methods 上添加注解，如 @ApiVersion(3)

• @ApiVersion(3)自定义注解，传递参数信息表示默认最低的版本限制。

总结

综上所述，大家更喜欢哪种方式？

[wonderfulcxm]

WordPress 的 rest API 是第二种，可能是因为它面向的用户什么水平的都有，为了简单，不用考虑再加一个域名。

[remember5]

@wonderfulcxm #1 是的，个人也比较倾向 url 路径区分

[maggch97]

你说的 1 和 3 根本没有一个成熟的 api 这么做吧，都是 2

[lkk]

2 吧。1 还要多来一个 DNS 策略

[gxvsko]

https://restfulapi.net/versioning/
还可以放到 Accept header 头里

[wolfie]

一般大厂对外 openapi 都是 2

[hsymlg]

做契约测试，类似 pact ，不用的接口及时过期或清理。git 本身就是控制版本的，再在接口上面加上版号，自我折磨嘛。

[otakustay]

1 涉及跨域太要命了，3 涉及参数拼接太麻烦了，基本全是 2 或者 header 传 X-API-Version

[Oktfolio]

https://github.com/micronaut-projects/micronaut-core/blob/4.0.x/src/main/docs/guide/httpServer/apiVersioning.adoc

[julyclyde]

如果有条件的话，用域名最好
等到将来，你都 v 好几了，还有几个赖着不走的 v1 客户端，可以直接掐了他们的服务，以绝后患

如果用路径的话，赖着不走的旧版本客户端，无论如何都会给你带来点儿负担的

querystring 显然是错误的，别想了

[remember5]

@maggch97 #3
@lkk #4
@wolfie #6
@otakustay #8
是的，个人也非常偏向于 2 ，且 SpringBoot 更改起来也比较方便

[remember5]

@gxvsko #5 这个不错，学习了，考虑结合项目改造，选择了路径区分
@Oktfolio #9 同上，感谢

[remember5]

@julyclyde #10 是的，域名的话，考虑到会对接三方以及跨域的风险，不过域名可以起到绝对的隔离，querystring 只是一种想法，并不成熟，也不理想。

[alen0206]

/api/v2

[humpy]

针对主楼的内容，直接 requestmapping 的 path 写上 v1 、v2 就行了，为什么还要发明一个注解呢

[remember5]

@hsymlg #7 App 业务中，需要兼容低版本，业务角度不属于过期代码

[remember5]

@humpy #15 感谢提醒，上面忘记补充了，直接在 ReuqestMapping 中添加 /v1 /v2 的确更加直观，但注解方式更加灵活，可控制最低版本限制，版本继承等优点。

[xuanbg]

不在单个接口 url 上面区别版本的话，不知道有多少坑。。。。