首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >APP接口升级设计策略API版本管理规范版本控制模式API版本升级方案约定和案例使用场景

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

作者头像
黄小怪
发布于 2018-12-06 03:16:39
发布于 2018-12-06 03:16:39
5K00
代码可运行
举报
文章被收录于专栏:小怪聊职场小怪聊职场
运行总次数:0
代码可运行

API版本管理规范

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

版本控制模式

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

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
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指定版本

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
: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版本获取的是总资产和安全边界的数据,在后续的版本获取的是保证金率和安全边界的数据。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
@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获取:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
: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中,旧的接口不需要处理,客户端自己区分。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
@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(方便回滚)。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
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兼容。

本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2018.11.05 ,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
.NET WebAPI 实现 接口版本控制并打通 Swagger支持
我们在开发 webapi 项目时如果遇到 api 接口需要同时支持多个版本的时候,比如接口修改了入参之后但是又希望支持老版本的前端(这里的前端可能是网页,可能是app,小程序 等等)进行调用,这种情况常见于 app,毕竟网页前端我们可以主动控制发布,只要统一发布后所有人的浏览器下一次访问网页时都会重新加载到最新版的代码,但是像 app 则无法保证用户一定会第一时间升级更新最新版的app,所以往往需要 api接口能够同时保持多个版本的逻辑,同支持新老版本的调用端app进行调用。
乌拉栋
2022/10/28
1.3K0
.NET WebAPI 实现 接口版本控制并打通 Swagger支持
ASP.NET Core 实战:构建带有版本控制的 API 接口
  在上一篇的文章中,主要是搭建了我们的开发环境,同时创建了我们的项目模板框架。在整个前后端分离的项目中,后端的 API 接口至关重要,它是前端与后端之间进行沟通的媒介,如何构建一个 “好用” 的 API 接口,是需要我们后端人员好好思考的。   在系统迭代的整个过程中,不可避免的会添加新的资源,或是修改现有的资源,后端接口作为暴露给外界的服务,变动的越小,对服务的使用方造成的印象就越小,因此,如何对我们的 API 接口进行合适的版本控制,我们势必需要首先考虑。
程序员宇说
2019/09/11
1.4K0
ASP.NET Core 实战:构建带有版本控制的 API 接口
用户案例 | 蜀海供应链基于 Apache DolphinScheduler 的数据表血缘探索与跨大版本升级经验
蜀海供应链是集销售、研发、采购、生产、品保、仓储、运输、信息、金融为一体的餐饮供应链服务企业。2021年初,蜀海信息技术中心大数据技术研发团队开始测试用Apache DolphinScheduler作为数据中台和各业务产品项目的任务调度系统工具。本文主要分享了蜀海供应链在海豚早期旧版本实践过程中的探索创新和在跨大版本升级部署过程中的经验,希望对大家有所启发和帮助。
用户6070864
2023/09/09
1.8K0
用户案例 | 蜀海供应链基于 Apache DolphinScheduler 的数据表血缘探索与跨大版本升级经验
人人都是 API 设计者:我对 RESTful API、GraphQL、RPC API 的思考
有一段时间没怎么写文章了,今天提笔写一篇自己对 API 设计的思考。首先,为什么写这个话题呢?其一,我阅读了《阿里研究员谷朴:API 设计最佳实践的思考》一文后受益良多,前两天并转载了这篇文章也引发了广大读者的兴趣,我觉得我应该把我自己的思考整理成文与大家一起分享与碰撞。其二,我觉得我针对这个话题,可以半个小时之内搞定,争取在 1 点前关灯睡觉,哈哈。
用户2781897
2019/05/17
1.1K0
REST API设计指导——译自Microsoft REST API Guidelines(四)
前面我们说了,如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?这里我们不得不提到REST API。
雪雁-心莱科技
2018/12/27
2.4K0
Flink从1.7到1.12版本升级汇总
最进再看官方flink提供的视频教程,发现入门版本因为时间关系都是基于1.7.x讲解的. 在实际操作中跟1.12.x版本还是有差距的, 所以整理一下从1.7 版本到1.12版本之间的相对大的变动. 做到在学习的过程中可以做到心里有数.
王知无-import_bigdata
2021/09/22
3K0
Midjourney开发者必看:MJ V7接口API Key获取及使用全攻略
在人工智能(AI)绘画这股浪潮里,Midjourney绝对是个响当当的名字。但它不仅仅是个工具那么简单,更像一个充满活力的独立研究实验室,总想着用新点子拓宽我们的思维边界,点燃我们脑海里的想象火花。这篇文章,就是你的Midjourney深度游向导:从它是怎么工作的、有啥看家本领、一路怎么升级打怪过来的,到怎么写好“咒语”(提示词)画出神图,甚至还会手把手带你看看怎么(非官方地)拿到和使用API密钥。最后,咱们再一起畅想一下,这玩意儿在未来能玩出什么新花样。
攻坚克难的那份表
2025/05/17
9290
《移动互联网技术》第十一章 Android应用工程案例: 掌握Android系统的需求分析和设计以及 Android项目的程序测试和版本管理方法
《移动互联网技术》课程是软件工程、电子信息等专业的专业课,主要介绍移动互联网系统及应用开发技术。课程内容主要包括移动互联网概述、无线网络技术、无线定位技术、Android应用开发和移动应用项目实践等五个部分。移动互联网概述主要介绍移动互联网的概况和发展,以及移动计算的特点。无线网络技术部分主要介绍移动通信网络(包括2G/3G/4G/5G技术)、无线传感器网络、Ad hoc网络、各种移动通信协议,以及移动IP技术。无线定位技术部分主要介绍无线定位的基本原理、定位方法、定位业务、数据采集等相关技术。Android应用开发部分主要介绍移动应用的开发环境、应用开发框架和各种功能组件以及常用的开发工具。移动应用项目实践部分主要介绍移动应用开发过程、移动应用客户端开发、以及应用开发实例。 课程的教学培养目标如下: 1.培养学生综合运用多门课程知识以解决工程领域问题的能力,能够理解各种移动通信方法,完成移动定位算法的设计。 2.培养学生移动应用编程能力,能够编写Andorid应用的主要功能模块,并掌握移动应用的开发流程。 3. 培养工程实践能力和创新能力。  通过本课程的学习应达到以下目的: 1.掌握移动互联网的基本概念和原理; 2.掌握移动应用系统的设计原则; 3.掌握Android应用软件的基本编程方法; 4.能正确使用常用的移动应用开发工具和测试工具。
猫头虎
2024/04/08
2350
Kubernetes集群部署相关
free -h,显示内存和利用率 用swapon -s可以检查特定分区,逻辑卷或文件的交换,-s是摘要的含义,用它来获取交换的详细信息,以千字节为单位 或者使用top命令 vmstat,可以用该命令查看交换和交换信息,无法查看交换的总值
用户1413827
2023/11/28
7640
Kubernetes集群部署相关
设计模式学习笔记整理手册
单一职责原则定义:一个对象应该只包含单一的职责,并且该职责被完整地封装在一个类中。
SmileNicky
2019/04/22
1.3K0
设计模式学习笔记整理手册
springcloudAlibaba&rancher【后端专题】
DevOps即Development和Operations的组合词,是一组过程、方法与系统的统称,用于促进开发应用程序或软件工程、技术运营和质量保障QA部门之间的沟通、协作与整合。
高大北
2022/12/20
2.5K0
springcloudAlibaba&rancher【后端专题】
微服务接口设计原则
本文结合自身后台开发经验,从高可用、高性能、易维护和低风险(安全)角度出发,尝试总结业界常见微服务接口设计原则,帮助大家设计出优秀的微服务。 1.前言 微服务是一种系统架构风格,是 SOA(面向服务架构)的一种实践。微服务架构通过业务拆分实现服务组件化,通过组件组合快速开发系统,业务单一的服务组件又可以独立部署,使得整个系统变得清晰灵活: 原子服务 独立进程 隔离部署 去中心化服务治理 一个大型复杂的软件应用,都可以拆分成多个微服务。各个微服务可被独立部署,各个微服务之间是松耦合的。现如今后台服务大部分以微
腾讯技术工程官方号
2022/08/26
1.4K0
微服务接口设计原则
第3课 Kubectl常用命令详解
通过配置文件名或stdin创建一个集群资源对象。 支持JSON和YAML格式的文件。
辉哥
2021/11/24
2.8K0
第3课 Kubectl常用命令详解
Java 设计模式最佳实践:6~9
这一章将描述反应式编程范式,以及为什么它能很好地适用于带有函数元素的语言。读者将熟悉反应式编程背后的概念。我们将介绍在创建反应式应用时从观察者模式和迭代器模式中使用的元素。这些示例将使用反应式框架和名为 RxJava(版本 2.0)的 Java 实现。
ApacheCN_飞龙
2023/04/23
1.9K0
基于Web的仓库管理系统的设计与实现
摘 要 仓库物品的管理是与我们的日常生活息息相关的一个重大问题。随着我国经济飞速的发展,改革开放的不断深入,企业要想在激烈的市场竞争中立于不败之地,要想继续的发展与生存,没有现代化的管理方式与方法是万万不行的,仓库管理的全面信息化、自动化则是在其中占有极其重要的地位。仓库管理信息系统则是在此需求背景下开始研制并开发的。在此篇文章中严格按照软件工程思想,设计并实现了一个仓库信息管理系统。介绍了系统从需求分析,逻辑设计,总体设计,详细设计以及系统测试、实施各阶段的主要内容和成果,包括系统结构图、业务流程图数据流程图、物理表实现及其关系、功能模块算法流程、界面设计等等。 关键字 仓库; 软件工程; 系统开发
全栈程序员站长
2022/10/03
1.7K0
SpringCloud - 待整理
1.cloud-provider-payment8001微服务提供者支付Module模块
郭顺发
2021/12/17
7270
springcloudAlibaba+devops
springcloudAlibaba&rancher【后端专题】 简介:用户增长的数据分析模型AARRR
高大北
2022/12/20
1.4K0
springcloudAlibaba+devops
Java开发手册——嵩山版(清幽现云山,虚静出内功)
《Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结,经历了多次大规模一
红目香薰
2022/11/29
1.7K0
Java开发手册——嵩山版(清幽现云山,虚静出内功)
Flutter技术与实战(5)
##### 从原生页面跳转至Flutter页面 * Flutter 本身依托于原生提供的容器(iOS 为 FlutterViewController,Android 为 Activity 中的 FlutterView),所以我们通过初始化 Flutter 容器,为其设置初始路由页面之后,就可以以原生的方式跳转至 Flutter 页面了。
八归少年
2022/06/29
16.4K0
Flutter技术与实战(5)
TensorFlow Lite,ML Kit 和 Flutter 移动深度学习:6~11
认证是任何应用中最突出的功能之一,无论它是本机移动软件还是网站,并且自从保护数据的需求以及与机密有关的隐私需求开始以来,认证一直是一个活跃的领域。 在互联网上共享的数据。 在本章中,我们将从基于 Firebase 的简单登录到应用开始,然后逐步改进以包括基于人工智能(AI)的认证置信度指标和 Google 的 ReCaptcha。 所有这些认证方法均以深度学习为核心,并提供了一种在移动应用中实现安全性的最新方法。
ApacheCN_飞龙
2023/04/27
24.3K0
TensorFlow Lite,ML Kit 和 Flutter 移动深度学习:6~11
推荐阅读
相关推荐
.NET WebAPI 实现 接口版本控制并打通 Swagger支持
更多 >
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档