移动 APP 接口规范

一、接口概述

1.1 接口规范意义

接口是用于数据的交互，接口文档是供需双方的开发规范。移动应用接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。接口文档往往是在需求评审完成之后就需要开始编写的，并尽快文档定下来，良好的接口文档能有效减少开发人员的沟通成本。

1.2 接口分类

1.2.1 查询类接口

查询类接口是指客户端传递一些参数，服务端根据参数依据需求，前往数据库查询需要的结果返回数据的一类接口。返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。

第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。
第二种比如获取客户，客户端把用户的身份信息上传到接口，服务器返回此身份下的所有客户数组集合。

1.2.2 操作类接口

操作类接口是指客户端通过接口进行一些增删改的操作。比如新增一个客户，修改客户信息，或者删除一个客户。服务器一般返回执行的状态（成功/失败），有的需要返回执行结果的一些信息，比如新增客户后，返回客户的ID。

1.2.3 上传下载类接口

上传下载类接口是涉及到文件传输的接口。比如上传头像，需要上传图片到服务器，服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像，需要读取网络图片文件，在手机上进行显示。定义这类接口时要注意是否有必要限定上传文件的的大小。

1.2.4 推送类接口

除了客户端主动去请求服务端，获取需要信息之外。有时候，也存在服务端有消息需要通知客户端的情况，这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间内循环请求解决，也可以通过第三方专业推送解决。也可以通过自己使用socket或者xmpp等协议进行开发。

二、接口编写原则

2.1 实用性

数据格式：推荐使用JSON格式数据，因为JSON有较好的跨平台性，以及数据格式占用字节数较少，当然也可采用XML、TEXT作为程序开发辅助。
接口响应时间：APP有别于WEB服务，对服务器端要求是比较严格的，在移动端有限的带宽条件下，要求接口响应速度要快，所有在开发过程中尽量选择效率高的框架。
数据量：按需分配，APP客户端需要什么数据就返回什么数据，过多的数据量影响处理速度，最重要的是影响传输效率和浪费用户流量。
API缓存：这点比较重要，不管是文件缓存还是memcache缓存。

2.2 易用性

接口、参数命名准确：论是接口还是参数，命名都应该有意义，让人一目了然。
接口拆分合理：如果不是复杂的页面，尽可能就使用一个接口；在很多的APP页面都有广告、焦点图、文章列表等，对于这些不同格式的数据，不可能都分配一个接口，这样加大了APP请求接口数，影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端。
接口数据、状态：接口必须提供明确的数据状态信息，不管是成功的，还是失败的，都必须返回给APP客户端。
可扩展：方便后期功能性调整，接口应具备可扩展性：文案与图片尽量由后端下发；数据列表化，灵活可配。

2.3 安全性

接口安全：目前一般都是在APP客户端和服务器通过约定的算法，对传递的参数值进行验证匹配。但是如果APP程序被反编译，这些约定的算法就会暴露，特别是在安卓APP中，有了算法，完全就可以通过验证模拟接口请求。
加密规范：在传递用户名密码时，应采用规范的加密算法如MD5、RSA、DES，进行数据通信请求。
接口版本控制：对于接口版本控制，需要应对不断的APP版本升级，新、旧接口的处理，因而需要关注接口版本控制。
时间戳：接口请求和响应都加时间戳，通过对时间戳的验证，可以一定程度上防止重放攻击。

1
2
3

* 响应数据中包含用户隐私的字段数据，需要加 * 号
* 请求参数中包含用户隐私的字段参数，需要加密传输
* 参数签名匹配，防止篡改

三、接口设计原则

尽量减少参数传递（尽量少的数据接收交互）：在客户端发起HTTP请求接口操作时，应减少参数传递，如某些操作只需要ID不需要其他参数，这时候就应该只传递ID这个参数。
尽量避免接口重复性(尽量用少的链接传输多的数据)：在客户端APP调用接口时，尽量提高接口复用性，减少HTTP请求，提高程序稳定性。
数据类型规范：客户端APP调用接口时，应标注参数数据类型，以及是否可为空或者默认字段，如标注了Int型字段，就不能返回“null”的String类型字段，否则容易造成程序APP出现数据类型解析异常。
设置调用html页面单独列表：调用html页面应标明是否传递安全校验参数，建议表格中采用是或者否单独字段标识。
编码规范：整个API接口开发过程中，应标注接口编码方式，目前建议采用UTF-8编码，UTF-8通用性以及URL请求方面都较规范。
请求方式：编写API接口应该标注请求方式，请求方式一般有GET和POST方式
GET和POST方式：在数量较小情况下可以使用GET方式，但数据量超过1024字节就应该采用POST方式，避免出现请求失败或者请求异常的问题。
返回接口调用状态：所有API接口都应该统一标识调用的成功失败信息和规范错误编码信息，以及必要的提示字段信息。
安全机制：接口应规范验证签名机制，用户登录后统一调用KEY对接口安全验证。（关于KEY机制需由接口开发人员定义），对于安全系数要求较高的接口应该使用HTTPS请求，比如支付接口，订单接口，用户信息接口。
参数说明：应标注参数名称、是否必选、数据类型及范围、说明以及“否（必选）”传递默认的参数。
瘦客户端原则：客户端尽量只负责展示逻辑，不处理业务逻辑；客户端不处理金额的计算；客户端少处理请求参数的校验与约束提示。
考虑移动端平台特点：接口不仅仅是提供数据和功能就完事了，更应该充分考虑移动端的特性，为移动端提供更加方便、快捷的接口。
接口设计考虑缓存，尽量通过预加载降低对网络的依赖，首页数据可以传输更多内容，后续页可以传输索引数据。
对于移动客户端来说，by function (多个 API)需要多次网络交互，效率不高，也会给客户端实现增加复杂度。通常这种情况尽可能通过在服务器端 gateway 的方式来解决。最终提供 by page (统一 API)的接口。

一些移动端平台的数据约定：

时间日期型数据:直接返回格式化后的时间字符串或者直接返回时间戳
数字类型和文本类型:统一使用字符串格式
布尔值类型:统一使用字符串”0”和”1”来表示假和真
如果返回值是一个array，空数据则返回一个空array,如果返回值是一个对象，空数据则返回一个空对象
不返回 Null 类型数据
对于客户端，必须用个全局的函数来处理所有 api 的返回数据，需要有一个机制：对于某个客户端需要数据，如果api中缺失，客户端自动补上并给予默认值

四、文档编写规范

接口文档应该包含的几大类信息：目录、文档修订历史、名词解释、数据类型、系统出入参、接口描述、约定参数、常见响应码说明。接口文档要清晰、明了，包含多少个接口，每个接口的地址、参数、请求方式、数据交换格式、返回值等都要写清楚，对于字段参数应采用表格的形式规范说明。每一版的接口文档都应该有与需求文档对应的版本号。

1. 清晰的目录：目录的编写是为了APP开发人员快速定位需要的接口信息，使开发人员在最短的时间内找到需要的接口，同时也会对编写API接口人员后期的维护修改提高效率。

2. 文档修订历史：记录日期、文档版本、修改内容、修订人等信息，每一版变更的内容应该以红色文字标记，便于阅读。

日期	版本	内容	修改人
xxxx年xx月xx日	v1.0.1	部分接口改动	xxx

3. 名词解释：对文档中一些关键字的解释，方便在编写特定业务接口时直接使用，无需再进行说明。

4. 数据类型：基本数据类型。

|序号|类型|类型描述|参考|
|:—:|:—:|:—:|:—:|:—:|
|1|Number|数字类型|整数、长整型、单精度、双精度|
|2|String|字符串类型||
|3|Object|对象类型|任意对象类型|
|4|Boolean|布尔类型|true 或 false|
|5|Array|列表||
|6|Array<number>|数字列表|列表中必须是同一种数字类型|
|7|Array<string>|字符串列表||
|8|Array<object>|对象列表|列表中必须是同一种对象类型|
|9|Array<boolean>|布尔列表||

5. 符号定义：强制域、条件域和选用域。

序号	序号缩写	序号性质	符号说明
1	M	强制域（Mandatory）	此域为必选，否则将被认为格式出错
2	C	条件域（Conditional）	此域在一定条件下必选
3	O	可选域（Optional）	此域由发送方自选

6. 系统请求参数：操作系统、手机唯一标识码、当前客户端版本号、手机系统版本号、手机型号、数字签名、接口版本号。

名称	说明	类型	必填	最大长度	备注
system	操作系统	String	M		00-pc 01-Android 02-iOS
imei	手机 IMEI 码	String	M/C	15	system 为 01 时必填
currentVersion	当前客户端版本号	String	M	20
systemVersion	手机平台版本号	String	M	10
model	手机型号	String	M	20	如 N9006
sig	数字签名	String	C
inteVersion	接口版本号	String	M	10	如 1.0.1

7. 系统响应参数：响应码、响应消息和业务数据。

名称	类型	必填	最大长度	描述
code	String	M	6	响应码
msg	String	M	128	响应信息
data	Object	M		任意类型，由具体接口定义

8. 业务接口描述信息：接口名称、接口描述、请求方式、测试地址、生产地址、备注。

参数说明：参数名、含义、类型、长度、必填、备注。
参数格式：请求参数格式、响应参数格式。