Android开发规范：API接口通用设计规范(1)

1. Android开发规范：API接口安全设计规范

2. Android开发规范：API接口通用设计规范

文章目录

• 通用规范

• • 版本号

• 请求参数

• 返回值

• 接口变更

• API格式

• • 传统格式

• RestFul API

通用规范

==============================================================

版本号

---

每一组API接口需要对应一个大版本号，大版本号一般是跟app的大版本对应的。

比如app第一版本我们叫v1，app第二版本经过改版后，接口返回内容一般也会有变化，我们叫v2。

以Restful API风格为例：

https://www.example.com/api/v{x}/，一般我们会在api接口的前面位置加上v{x}这个值。

x分两种情况：

1. 整型表示大版本号，比如v1、v2。

2. 浮点型表示小版本号，是对是大版本定义的业务接口的补充，比如v1.1。

举个例子：

1. https://www.example.com/api/v1/userinfo

表示v1这个大版本的app，有一个userinfo业务类型的接口；

2. https://www.example.com/api/v2/userinfo

表示v2这个大版本的app，同样有一个userinfo业务类型的接口；

3. https://www.example.com/api/v2.1/userinfo

表示v2这个大版本中，userinfo这个业务接口进行了一些细微调整。

请求参数

---

请求参数由公共请求参数+业务请求参数组合而成。

1. 公共请求参数

| 参数名 | 参数类型 | 是否必填 | 描述 |

| — | — | — | — |

| nonce | String | 是 | 防重放攻击 |

| timestamp | String | 是 | 防重放攻击 |

| sign | String | 是 | 请求参数的签名 |

| accessToken | String | 否 | 鉴权标志，用于登录判断 |

| appKey | String | 是 | 防篡改 |

| version | String | 否 | 客户端版本号 |

其中version表示客户端版本号，此处将其传给服务器，由服务器根据客户端版本号进行一定的业务逻辑判断。

2)业务请求参数

以登录为例：

| 参数名 | 参数类型 | 是否必填 | 描述 |

| — | — | — | — |

| name | String | 是 | 姓名 |

| password | String | 是 | 密码 |

一个完整的URL如下（以传统URL格式为例）：

https://www.example.com/api/v1/getUserInfo.do?nonce=3ec934e8-81b9-492e-933d-a5dc41eb15bd&timestamp=1567118072&sign=c1741210c06f3827d1d2f3bfd1f1fc2878377307&accessToken=LvzFEeQSuU9B4DrnoPO9D4CL3ZhKCetZ%2FRckCWQlgb9qmNLmgCKxkymoC4pEs5LFw1lSAGZXKvHe%0AvpFgXKmAAQ%3D%3D&appKey=3b6af23db66c69b7131a8186f90fe663&name=jack&password=123456

返回值

---

使用Json格式（而不是XML）返回API请求结果。Json格式简洁，传输数据量小，而且能展示复杂的数据结构。

{

“body”:{

},

“code”:0,

“msg”:“”

}

code：API接口执行状态，比如0表示成功，-100表示网络超时，-200表示鉴权失败等等；

msg：非成功状态下，需要说明的信息，一般这个是服务器和code状态码一一对应定义；

body：返回的具体数据，也是Json格式。

客户端需要对所有code的值进行一一处理。

接口变更

---

一般来说一个API接口投入使用后，除非这个接口确定废弃不再使用，一般情况下不能对这个接口进行修改，比如API的请求参数和返回值，否则会对使用此API接口的APP带来不可预估的影响，最严重的就是崩溃。

如果接口需要变更，那我们需要保证API接口的变更能够向下兼容，就是API的变更不影响原有使用API接口的客户端。

如果不能够保证向下兼容，那么只有新建新的API接口。

接口变更有以下两种情况：能够向下兼容、不能兼容需要新建新的API接口。

以下是一个原始的json格式的返回值：

{

“id”: 1,

“name”: “jack”,

“address”: “usa”

}

原始URL：https://www.example.com/api/v1/userinfo

1. 向下兼容

(1)url的请求参数新增字段，比如

https://www.example.com/api/v1/userinfo?currentTime=2019/12/12

新增一个请求参数currentTime，不影响当前API接口的使用。

(2)url的返回数据结构增加字段，比如：

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数初中级Android工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则近万的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年Android移动开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Android开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！

如果你觉得这些内容对你有帮助，可以扫码获取！！（备注：Android）

最后

分享一份NDK基础开发资料

分享内容包括不限于高级UI、性能优化、架构师课程、NDK、混合式开发（ReactNative+Weex）微信小程序、Flutter等全方面的Android进阶实践技术；希望能帮助到大家，也节省大家在网上搜索资料的时间来学习，也可以分享动态给身边好友一起学习！

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！

5-1713258385099)]

分享内容包括不限于高级UI、性能优化、架构师课程、NDK、混合式开发（ReactNative+Weex）微信小程序、Flutter等全方面的Android进阶实践技术；希望能帮助到大家，也节省大家在网上搜索资料的时间来学习，也可以分享动态给身边好友一起学习！

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！