接口 API 版本管理怎么写比较合适呢？

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

已注册用户请登录

这是一个创建于 812 天前的主题，其中的信息可能已经有所发展或是发生改变。

现在的需求是对 API 进行版本管理。
目前计划是使用 url 带版本号的形式。
XXX/v2.0/test

目前框架中有两种写法都能实现这个需求，我觉得应该是使用注解更好一点，但是没太想好具体的优势是什么呢？
使用注解的写法。
@UrlVersion("v2.0")
@GetMapping("test")
publc R<Boolean> test() {}
直接使用地址的写法
@PostMapping("/v2.0/test")
public R<Boolean> test2() {}

问了一下 AI ，chatgpt 说：
1. 更加灵活: 使用注解可以动态地指定 API 版本，不需要修改链接地址。这样可以方便地进行版本升级和管理。
2. 代码可读性更高: 使用注解可以直观地指定 API 版本，提高了代码的可读性和可维护性。
3. 模块化管理: 使用注解可以将 API 版本与具体的方法进行绑定，使得版本管理更加模块化。不同的方法可以使用不同的版本注解，从而实现对每个方法的精确控制。
4. 可扩展性更强: 使用注解可以方便地扩展更多的版本管理功能，例如可以添加更多的版本控制策略、版本切换的拦截器等。

大家怎么看待这个事情呢？对于前端来说用起来应该是一样的，区别就是在后端这里。

注解

版本

API

test

9 条回复 2023-11-15 19:03:38 +08:00

Seulgi

2023 年 11 月 15 日

我倾向于 2 ，主要是因为接口地址，一次定下来，后面不可能变更，而且 2 更方便查询，idea 的功能也能搜索到但是 1 不行，1 不仅隐藏了接口实际地址，还多了一层 aop ，我觉得怪麻烦的。排查问题都可能多一层。
我更推荐的就是 v1controller 放 v1 接口，v2controller 放 v2 接口，层次更清晰。
但是你说的是 api 版本管理，其实我更倾向于你用 header 来做，接口地址不变，header 里塞一个 apiver ，然后用 1 。

chendy

2023 年 11 月 15 日

如果是给前端用的接口，个人理解是不需要版本控制，避免破坏性的修改就行

如果是开放接口，注解的方式看着更优雅一点，chatgpt 说的差不多了

cnzmz

2023 年 11 月 15 日

@chendy 现在是有接口变更传参了，想尽量保持原有接口的兼容性。

cnzmz

2023 年 11 月 15 日

@Seulgi 其实要变更的接口并不是很多，用两个 controller 是不是也不太合适。只是某些接口变更传参了，想尽可能保留原来的兼容性。

burymme11

2023 年 11 月 15 日

是业务代码嘛？如果是，个人建议用 2 ，我觉得业务代码的可读性和查询排错的方便性，远远高于兼容性。

Seulgi

2023 年 11 月 15 日

@cnzmz #4 你如果只是因为要升级接口，比如多一些参数少一些参数，你就用 2 完事了。这种场景就是说我两个接口都要保留，原因就是因为部分老版本 app 需要请求到老的接口，并且能通，不影响用户使用。当然也可以改 v1 接口返回个错误 msg：请升级最新版本 app 。我并不是提倡你去用两个 controller ，只是说如果你只是单纯的因为业务问题要升级接口，就写个新接口完事，没必要为这种场景去设计个注解，还破坏了接口的可读性和查找性。

chendy

2023 年 11 月 15 日

@cnzmz 给前端的接口，如果要修改，可以考虑直接弄个新接口，前端切换完成之后老接口删掉
因为接口版本控制对于前后端这种场景作用太小了，新版接口上线约等于旧版本接口下线，不需要弄得太复杂

cnzmz

2023 年 11 月 15 日

@Seulgi
@chendy
我理解你们说的了，那么接口版本控制的场景是什么呢？

IvanLi127

2023 年 11 月 15 日 via Android

一般来说，版本控制和 url 路径不一定有关系，但是你已经决定用 url 路径区分了，那只要你能确保以后不换方案，就用 2 。