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

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

  •  
  •   remember5 · 2022-09-29 11:19:25 +08:00 · 2494 次点击
    这是一个创建于 546 天前的主题,其中的信息可能已经有所发展或是发生改变。

    背景

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

    多版本实现方式

    Api 版本控制的方式:

    1. 域名区分管理,即不同的版本使用不同的域名,v1.api.test.comv2.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)自定义注解,传递参数信息表示默认最低的版本限制。

    总结

    综上所述,大家更喜欢哪种方式?

    18 条回复    2022-09-30 08:46:54 +08:00
    wonderfulcxm
        1
    wonderfulcxm  
       2022-09-29 11:23:02 +08:00 via iPhone
    WordPress 的 rest API 是第二种,可能是因为它面向的用户什么水平的都有,为了简单,不用考虑再加一个域名。
    remember5
        2
    remember5  
    OP
       2022-09-29 11:29:38 +08:00
    @wonderfulcxm #1 是的,个人也比较倾向 url 路径区分
    maggch97
        3
    maggch97  
       2022-09-29 11:58:02 +08:00 via Android
    你说的 1 和 3 根本没有一个成熟的 api 这么做吧,都是 2
    lkk
        4
    lkk  
       2022-09-29 13:39:41 +08:00
    2 吧。1 还要多来一个 DNS 策略
    gxvsko
        5
    gxvsko  
       2022-09-29 13:45:01 +08:00   ❤️ 1
    https://restfulapi.net/versioning/
    还可以放到 Accept header 头里
    wolfie
        6
    wolfie  
       2022-09-29 13:48:34 +08:00
    一般大厂对外 openapi 都是 2
    hsymlg
        7
    hsymlg  
       2022-09-29 13:52:19 +08:00
    做契约测试,类似 pact ,不用的接口及时过期或清理。git 本身就是控制版本的,再在接口上面加上版号,自我折磨嘛。
    otakustay
        8
    otakustay  
       2022-09-29 14:14:44 +08:00
    1 涉及跨域太要命了,3 涉及参数拼接太麻烦了,基本全是 2 或者 header 传 X-API-Version
    julyclyde
        10
    julyclyde  
       2022-09-29 14:55:16 +08:00
    如果有条件的话,用域名最好
    等到将来,你都 v 好几了,还有几个赖着不走的 v1 客户端,可以直接掐了他们的服务,以绝后患

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

    querystring 显然是错误的,别想了
    remember5
        11
    remember5  
    OP
       2022-09-29 16:56:35 +08:00
    @maggch97 #3
    @lkk #4
    @wolfie #6
    @otakustay #8
    是的,个人也非常偏向于 2 ,且 SpringBoot 更改起来也比较方便
    remember5
        12
    remember5  
    OP
       2022-09-29 16:57:53 +08:00
    @gxvsko #5 这个不错,学习了,考虑结合项目改造,选择了路径区分
    @Oktfolio #9 同上,感谢
    remember5
        13
    remember5  
    OP
       2022-09-29 16:59:57 +08:00
    @julyclyde #10 是的,域名的话,考虑到会对接三方以及跨域的风险,不过域名可以起到绝对的隔离,querystring 只是一种想法,并不成熟,也不理想。
    alen0206
        14
    alen0206  
       2022-09-29 17:47:36 +08:00
    /api/v2
    humpy
        15
    humpy  
       2022-09-29 18:22:44 +08:00 via iPhone
    针对主楼的内容,直接 requestmapping 的 path 写上 v1 、v2 就行了,为什么还要发明一个注解呢
    remember5
        16
    remember5  
    OP
       2022-09-29 22:00:20 +08:00
    @hsymlg #7 App 业务中,需要兼容低版本,业务角度不属于过期代码
    remember5
        17
    remember5  
    OP
       2022-09-29 22:10:19 +08:00
    @humpy #15 感谢提醒,上面忘记补充了,直接在 ReuqestMapping 中添加 /v1 /v2 的确更加直观,但注解方式更加灵活,可控制最低版本限制,版本继承等优点。
    xuanbg
        18
    xuanbg  
       2022-09-30 08:46:54 +08:00
    不在单个接口 url 上面区别版本的话,不知道有多少坑。。。。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1117 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 18:48 · PVG 02:48 · LAX 11:48 · JFK 14:48
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.