升级兼容规范¶
兼容性定义¶
兼容性变动¶
一般认为下面的情况是兼容的： 1. 增加新方法 2. 增加可选的参数 3. 修改参数为可选 4. 框架支持的话，参数的顺序也可以改 5. 删除入参 6. 参数是对象的话，其属性的变更参见2-5条。
不兼容性变动¶
一般认为下面的情况是不兼容的：
- 修改方法的名称
- 删除方法
- 增加必填的参数
- 修改参数为必填
- 修改参数和返回值的类型
- 删除返回参数
- 参数是对象的话，属性的变更参照3-6条。
兼容性checklist¶
| 类别 | 兼容 | 不兼容 |
|---|---|---|
| http接口变更 | 1.增加新方法 | 修改方法的名称 |
| 2.增加可选的参数 | 2.删除方法 | |
| 3.修改参数为可选 | 3.增加必填的参数 | |
| 4.框架支持的话，参数的顺序也可以改 | 4.修改参数为必填 | |
| 5.删除入参 | 5.修改参数和返回值的类型 | |
| 6.参数是对象的话，其属性的变更参见2-5条 | 6.删除返回参数 | |
| 7.参数是对象的话，属性的变更参照3-6条 | ||
| RPC接口变更 | 1.方法内部变动 | 1.修改方法的名称 |
| 2.新增方法 | 2.增加方法的参数 | |
| 3.修改方法的参数 | ||
| 4.删除方法的参数 | ||
| 5.删除方法 | ||
| 6.修改方法的返回值 | ||
| 数据库变更 | 1.新增字段值 | 1.新增字段 |
| 2.删除字段值 | 2.删除字段 | |
| 3.修改字段值 | 3.修改字段 | |
| MQ队列变更 | 1.新增队列 | 1.队列绑定变更 |
| 2.删除队列 |
兼容策略¶
版本号约定¶
版本号分为**X.Y.Z**三位，分别代表主版本号、次版本号和修订版本号。
当代码变更时，版本号按以下原则更新。 1. 业务上技术上大的变动规划，更新**X**位。 2. 新功能开发，版本迭代，需要更新**Y**位。 3. 小功能或bug修复，更新修订版本**Z**位。
工程版本¶
- common公共依赖维护单个版本，可由project统一管理
- 产品业务模块共用统一版本
- 其他模块可按需升级本身或依赖版本
兼容规则¶
以下兼容仅讨论客户端跟服务端之间的兼容，服务端之间的兼容可以通过服务端的升级无感支持。
兼容方式¶
如图所示：
- 无版本，即平台的 API 永远只有一个版本，所有的用户都必须使用最新的 API，任何 API 的修改都会影响到平台所有的用户。甚至平台的整个生态系统。
- 点对点，即平台的 API 版本自带版本号，用户根据自己的需求选择使用对应的 API，需要使用新的 API 特性，用户必须自己升级
- 兼容性版本控制，和
点对点一样，平台只有一个版本，但是最新版本需要兼容以前版本的 API 行为。 - 多版本共存、兼容性版本控制，
点对点跟兼容性版本控制的结合体，同时存在多个版本API，且每个API版本可向下兼容多个版本客户端
推荐采用图第三种兼容方式，可支持一定复杂性的兼容，相对操作简单
版本兼容性¶
| 主版本 | 次版本 | 修订版本 |
|---|---|---|
| 不兼容、强制更新 | 向下兼容N版、可客户端热修 | 绝对兼容 |
版本兼容性实施¶
各端版本按需升级¶
服务端兼容性升级¶
接口兼容¶
接口版本控制模式¶
- HTTP Header指定版本
Host: test9.zhixueyun.com Connection: keep-alive Accept: */* X-Requested-With: XMLHttpRequest Authorization: Bearer__7ed2d2c97248b66d937c70dfef40ce7d Referer: https://test9.zhixueyun.com/ Accept-Encoding: gzip, deflate, br Accept-Language: zh-CN,zh;q=0.9 api-version:9.6.8 - API（URL）自带版本
https://test9.zhixueyun.com/api/v1/course-study/external-activity/list?_t=1541397626404
接口升级约定¶
-
小版本升级（Header指定版本） 小版本的更新，在原接口中做扩展，做兼容。 保障返回的JSON对象字段只增不删不改，客户端根据自己当前的版本显示不同的值。
-
大版本升级（新加版本接口） 无法兼容的接口，添加新版本接口。 采用新建Controller，甚至部署新的应用服务和nginx。例如：这次这个接口需要获取的数据是一个List的数据，而不是两个单独的值。 把修改的接口放在新的Controller中，旧的接口不需要处理，客户端自己区分。
数据兼容¶
实体变更¶
数据库表结构变更¶
- 表历史数据处理
- 已有队列数据等队列中旧数据消费完
缓存结构变更¶
- 旧缓存清理
MQ队列变更¶
- 废弃队列-删除
- 队列消费绑定变更-删除旧绑定关系
客户端非兼容性升级¶
强制更新¶
开启客户端的强制更新，未更新用户不能使用
代码热修¶
客户端从远程获取修改，热修兼容对应版本服务端API
版本兼容性执行流程¶
兼容性规范条例¶
- 【强制】开发组长在开发设计阶段必须输出影响点文档
| 影响点文档 |
|---|
| 功能点影响 |
| 中间件影响 |
| 历史数据兼容 |
| 兼容性版本评估 |
- 【强制】兼容性版本必须评审，以及输出评审结论邮件
- 【强制】老版本APP必须按兼容性版本做测试
- 【强制】测试必须输出版本兼容性报告
- 【强制】热修必须无兼容性变动
- 【强制】热修代码必须开发组长评审确认无兼容性问题后合并master
- 【强制】SQL变更必须依照评审流程审核通过后线上执行