如何更优雅管理API接口版本(v1/v2/v3…)

一、前言

一个web项目中,随着需求的变更或增加,API接口也会跟着变化,而如果APP发布后,已使用的接口肯定不能直接覆盖更新,需要新增升级版本接口和新的APP版本对应,因此多个版本接口更替后,如何更优雅管理不同版本接口代码,如何设计更直观的接口文档呈现给app端,这是我们后端工程师需要考虑的事情,下面总结接口版本管理经验。

二、接口代码版本规范

考虑到接口今后一定会进行版本迭代,因此一开始开发的时候,就需要对代码进行版本考量下的代码目标架构。

1. 控制器目录架构:

v1版本控制器目录:apps/controller/v1/……

v2版本控制器目录:apps/controller/v2/……

    在controller下增加子集文件夹:controller/v1/……、controller/v2/……等等,初始版本的接口全部放在v1下。

2. 接口路由设计

v1版本接口路由:/v1/login

v2版本接口路由:/v2/login

3. 不同版本控制器代码分类依据

(1)在发布APP前的所有代码,都属于v1版本代码;

(2)发布APP后,如果是新增加的需求,和已发布v1版本接口需求不冲突,新增控制器或接口,仍然属于v1版本代码;

(3)发布APP后,如果新增需求和v1已发布版本接口冲突,为了兼容老版本APP,必须在v2文件夹下新增控制器开发v2版本接口。

遵循以上分类原则,依次递推,严格区分不同版本接口代码,结合下一部分的接口文档,利于不同版本接口更新维护。

三、不同版本接口文档规范

版本迭代的接口,如果写在一起,APP真的要疯。最好能给APP一种重新开始的感觉,归零后,面对新接口,沟通起来新老接口文档区别明显,这就大大避免了无谓的撕逼。具体接口文档设计如下:

| —— 文档快捷导航

| —— 产品交互流程
    | —— v1版本
    | —— v2版本
    | —— ……

| —— 文档规范
    | —— 接口规范(接口地址,请求方式,接口参数,响应参数)
    | —— 接口文档规范
    | —— ……

| —— 开发计划

| —— 全局状态码

| —— 【v1】API文档
    | —— v1接口文档说明:包含v1接口基础地址、状态码、推送码等说明;
    | —— v1接口更新日志
    | —— 用户模块
    | —— 设备模块

| —— 【v2】API文档
    | —— v2接口文档说明:包含v2接口基础地址、状态码、推送码等说明;
    | —— v2接口更新日志
    | —— 用户模块
    | —— 设备模块
    

目录说明
    1. 文档快捷导航:根据接口目录结构,把不同版本接口汇总到表格中,然后对应加上接口文档链接,让APP对接时更容易定位接口位置,如:

【v1】API  [文档说明(带链接)]  [更新日志(带链接)] 
路由说明
/v1/login(带指向接口文档的链接)用户登录
/v1/user/info(带指向接口文档的链接)获取用户详情
…… 
【v2】API [文档说明(带链接)]  [更新日志(带链接)] 
路由说明
/v2/login(带指向接口文档的链接)用户登录
/v2/user/info(带指向接口文档的链接)获取用户详情
…… 

    2. 全局状态码:根据接口、推送等不同板块业务需求,对不同业务下的接口设计不同数字段的状态码,遇到这样设计下的状态码,沟通或出现问题更容易定位接口,如:

       指定200为正确响应状态码,500为服务器异常响应状态码;

       其他情况下,根据业务模块区分,用户功能相关接口非正确响应状态码指定1001~1050;设备操作功能模块非正确响应状态码指定1051~1100,以此类推。

    3. 接口更新日志说明:APP对接接口前,不用记录接口更新日志;APP对接后,接口输入参数或输出参数有变化时,需记录接口更新日志,接口更新日志记录模板如下:

格式如下:

日期【年-月-日】

1. 功能模块文件夹名称:接口名称(带链接),[增加 | 减少] [必要 | 非必要] [上报 | 响应] 参数 xxx;
2. 功能模块文件夹名称:接口名称(带链接),[增加 | 减少] [必要 | 非必要] [上报 | 响应] 参数 xxx;
……


如:

2019-04-22

1. 用户模块:用户登录,增加必要上报参数type;
2. 设备模块:添加设备,增加响应参数name字段;
……

2019-04-25

1. 用户模块:用户登录,增加必要上报参数type;
2. 设备模块:添加设备,增加响应参数name字段;
……
  • 10
    点赞
  • 35
    收藏
    觉得还不错? 一键收藏
  • 5
    评论
引用\[1\]: 这个报错是由于连接超时导致的。在你的问题中,你提到了uniapp上传图片后端报错I/O error on POST request for "http://localhost:9411/api/v2/spans": connect timed out。这个错误是由于后端请求超时导致的。可能是由于网络延迟或者后端服务器响应时间过长导致的连接超时。为了解决这个问题,你可以尝试以下几个方法: 1. 检查网络连接:确保你的网络连接正常,没有任何问题。你可以尝试重新连接网络或者使用其他网络进行测试。 2. 检查后端服务器:确认后端服务器是否正常运行,并且能够正常响应请求。你可以尝试访问后端服务器的其他接口或者使用其他工具进行测试。 3. 增加连接超时时间:如果你确定后端服务器正常运行,但是响应时间较长,你可以尝试增加连接超时时间。在Spring Boot中,你可以通过配置文件或者代码设置连接超时时间。 4. 检查请求地址:确保请求地址正确无误。在你的问题中,请求地址是"http://localhost:9411/api/v2/spans",请确保该地址是正确的,并且后端服务器能够正常接收该请求。 希望以上方法能够帮助你解决问题。如果问题仍然存在,请提供多的信息,以便我们能够好地帮助你解决问题。 #### 引用[.reference_title] - *1* [spingboot报错I/O error on POST request for “9411/api/v2/spans“: connect timed out](https://blog.csdn.net/cucgyfjklx/article/details/122428962)[target="_blank" data-report-click={"spm":"1018.2226.3001.9630","extra":{"utm_source":"vip_chatgpt_common_search_pc_result","utm_medium":"distribute.pc_search_result.none-task-cask-2~all~insert_cask~default-1-null.142^v91^insert_down28v1,239^v3^insert_chatgpt"}} ] [.reference_item] [ .reference_list ]
评论 5
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值