APP接口升级设计策略API版本管理规范版本控制模式API版本升级方案约定和案例使用场景

API版本管理规范

良好的API需要保持向前兼容,特别是在APP场景或者是其他第三方客户端的场景,产品需求的升级改进要求不影响现有的版本正常工作。因此对外暴露的所有API需要有统一的版本管理策略来应对兼容性问题。

版本控制模式

根据不同的应用场景,制定了两种API的版本控制模式: 1. API(URL)自带版本

https://www.fota.com/api/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.2/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.3/account/user/general?_t=1541397626404

2. HTTP Header指定版本

:authority: fota.com
:method: GET
:path: /api/account/user/general?_t=1541402217410
:scheme: https
accept: application/json, text/plain
accept-encoding: gzip, deflate, br
api-version:1.0.1

API版本升级方案约定和案例

开闭原则。 对于小版本的更新可以在单个接口中进行处理,对于大版本的更新,可以提供新的Controller,或新建服务部署新版本的接口,保留每个版本的服务。

1. 小版本升级 小版本的更新,在原接口中做扩展,做兼容。例如:一个应用场景,在1.0.1版本是获取的是总资产和保证金率的数据,在1.0.2版本获取的是总资产和安全边界的数据,在后续的版本获取的是保证金率和安全边界的数据。

@Authorization
@RequestMapping(value = "/general", method = RequestMethod.GET)
@ResponseBody
public Result getUserGeneralInfo() {
    String apiVersion = RequestHeaderContext.getInstance().getApiVersion();
    if (apiVersion.equals("1.0.1")){
        // 获取总资产和保证金率数据
    } else if (apiVersion.equals("1.0.2")){
        // 获取总资产和安全边界数据
    } else {
        // 获取保证金率和安全边界数据
    }
    Long userId = tokenUtil.getUserIdByLoginToken(RequestHeaderContext.getInstance().getToken());
    return accountManager.getUserGeneralInfo(userId);
}

当然,服务端也可以做兼容,把总资产、保证金率和安全边界的数据都返回,保障返回的JSON对象字段只增不删不改,客户端根据自己当前的版本显示不同的值。 apiVersion的值是从Header获取:

:authority: fota.com
:method: GET
:path: /api/contract/list?contractId=1027&_t=1541402217410
:scheme: https
accept: application/json, text/plain
accept-encoding: gzip, deflate, br
api-version:1.0.1

2. 大版本升级 无法兼容的接口,采用新建Controller,甚至部署新的应用服务和nginx。例如:这次这个接口需要获取的数据是一个List的数据,而不是两个单独的值。

把修改的接口放在新的Controller中,旧的接口不需要处理,客户端自己区分。

@Slf4j
@Controller
@RequestMapping("v1.2/account/user")
public class AccountControllerV2 extends BaseController {

    @Autowired
    private AccountManager accountManager;

    /**
     * 总资产和保证金率的List数据
     *
     * @return
     */
    @Authorization
    @RequestMapping(value = "/general", method = RequestMethod.GET)
    @ResponseBody
    public Result getUserGeneralInfo() {
        String apiVersion = RequestHeaderContext.getInstance().getApiVersion();
        if (apiVersion.equals("1.2.1")){
            // 获取总资产和保证金率数据
        } else if (apiVersion.equals("1.2.2")){
            // 获取总资产和安全边界数据
        } else {
            // 获取保证金率和安全边界数据
        }
        Long userId = tokenUtil.getUserIdByLoginToken(RequestHeaderContext.getInstance().getToken());
        return accountManager.getUserGeneralInfo(userId);
    }
}

在服务端新建Controller,甚至部署新的应用服务和nginx(方便回滚)。

https://www.fota.com/api/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.2/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.3/account/user/general?_t=1541397626404

使用场景

1. 接口变动非常大或者整个产品大版本发布 此种情况下可以采用URL自带版本的方式,提供新的Controller,甚至部署新的应用服务和nginx。URL中无版本号即走默认逻辑。

2. 常规的版本升级和BUGFIX 一般情况下使用HTTP Header中指定的版本号,在代码逻辑中进行判断就可满足需求。Header中无版本号即走默认处理逻辑。

3. 两种模式同时使用 URL自带模式用来处理大版本变动,当大版本已经升级完成,后续的小需求迭代仍然可以使用HEADER的方式来保持API兼容。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏JavaEdge

SpringCloud微服务实战(一) - 入门

就可以让应用变为Eureka服务器,这是因为spring boot封装了Eureka Server,让你可以嵌入到应用中直接使用

4449
来自专栏bdcn

CoreOS配置Docker 2375端口 原

8851
来自专栏云计算教程系列

如何在Ubuntu 14.04上使用Corosync,Pacemaker和浮动IP创建高可用性HAProxy设置

本教程将向您展示如何在Ubuntu 14.04上创建高可用性HAProxy负载均衡器设置,并支持浮动IP和Corosync / Pacemaker集群堆栈。HA...

3790
来自专栏纯洁的微笑

Spring Boot 2.0(五):Docker Compose+Spring Boot+Nginx+Mysql 实践

我知道大家这段时间看了我写关于 docker 相关的几篇文章,不疼不痒的,仍然没有感受 docker 的便利,是的,我也是这样认为的,I know your f...

5064
来自专栏用户3030674的专栏

Android sdk配置 常见问题及处理方法

Fetching https://dl-ssl.google.com/android/repository/addons_list-2.xml Fetched ...

1542
来自专栏跟着阿笨一起玩NET

server application unavailable IIS应用程序池 错误解决办法

出现错误信息如下: Server Application Unavailable The web application you are attempting...

2543
来自专栏吴伟祥

Docker安装Jenkins实现项目自动部署(Java Web项目) 顶

Jenkins是一个开源软件项目,是基于Java开发的一种持续集成工具,用于监控持续重复的工作,旨在提供一个开放易用的软件平台,使软件的持续集成变成可能。

5093
来自专栏Laoqi's Linux运维专列

Ansible 常用模块详细介绍

1523
来自专栏云鼎实验室的专栏

安全研究 | Jenkins 任意文件读取漏洞分析

2K2
来自专栏实战docker

Docker下kafka学习,三部曲之三:java开发

在前两章《Docker下kafka学习,三部曲之一:极速体验kafka》和《Docker下kafka学习,三部曲之二:本地环境搭建》中,我们通过命令行体验了ka...

3277

扫码关注云+社区

领取腾讯云代金券