V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
cnzmz
V2EX  ›  Java

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

  •  
  •   cnzmz · 359 天前 · 1793 次点击
    这是一个创建于 359 天前的主题,其中的信息可能已经有所发展或是发生改变。
    现在的需求是对 API 进行版本管理。
    目前计划是使用 url 带版本号的形式。
    XXX/v2.0/test

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

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

    大家怎么看待这个事情呢?对于前端来说用起来应该是一样的,区别就是在后端这里。
    9 条回复    2023-11-15 19:03:38 +08:00
    Seulgi
        1
    Seulgi  
       359 天前   ❤️ 2
    我倾向于 2 ,主要是因为接口地址,一次定下来,后面不可能变更,而且 2 更方便查询,idea 的功能也能搜索到但是 1 不行,1 不仅隐藏了接口实际地址,还多了一层 aop ,我觉得怪麻烦的。排查问题都可能多一层。
    我更推荐的就是 v1controller 放 v1 接口,v2controller 放 v2 接口,层次更清晰。
    但是你说的是 api 版本管理,其实我更倾向于你用 header 来做,接口地址不变,header 里塞一个 apiver ,然后用 1 。
    chendy
        2
    chendy  
       359 天前
    如果是给前端用的接口,个人理解是不需要版本控制,避免破坏性的修改就行

    如果是开放接口,注解的方式看着更优雅一点,chatgpt 说的差不多了
    cnzmz
        3
    cnzmz  
    OP
       359 天前
    @chendy 现在是有接口变更传参了,想尽量保持原有接口的兼容性。
    cnzmz
        4
    cnzmz  
    OP
       359 天前
    @Seulgi 其实要变更的接口并不是很多,用两个 controller 是不是也不太合适。只是某些接口变更传参了,想尽可能保留原来的兼容性。
    burymme11
        5
    burymme11  
       359 天前   ❤️ 1
    是业务代码嘛?如果是,个人建议用 2 ,我觉得业务代码的可读性和查询排错的方便性,远远高于兼容性。
    Seulgi
        6
    Seulgi  
       359 天前
    @cnzmz #4 你如果只是因为要升级接口,比如多一些参数少一些参数,你就用 2 完事了。这种场景就是说我两个接口都要保留,原因就是因为部分老版本 app 需要请求到老的接口,并且能通,不影响用户使用。当然也可以改 v1 接口返回个错误 msg:请升级最新版本 app 。我并不是提倡你去用两个 controller ,只是说如果你只是单纯的因为业务问题要升级接口,就写个新接口完事,没必要为这种场景去设计个注解,还破坏了接口的可读性和查找性。
    chendy
        7
    chendy  
       359 天前
    @cnzmz 给前端的接口,如果要修改,可以考虑直接弄个新接口,前端切换完成之后老接口删掉
    因为接口版本控制对于前后端这种场景作用太小了,新版接口上线约等于旧版本接口下线,不需要弄得太复杂
    cnzmz
        8
    cnzmz  
    OP
       359 天前
    @Seulgi
    @chendy
    我理解你们说的了,那么接口版本控制的场景是什么呢?
    IvanLi127
        9
    IvanLi127  
       359 天前 via Android
    一般来说,版本控制和 url 路径不一定有关系,但是你已经决定用 url 路径区分了,那只要你能确保以后不换方案,就用 2 。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1196 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 18:18 · PVG 02:18 · LAX 10:18 · JFK 13:18
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.