《移动开发接口及文档编写规范》V1.0

 
《移动开发接口及文档编写规范》V1.0文档说明
编写整理：童正刚 2015-05

一、概述

ü      有关接口

1、接口是纯数据的交互

APP接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。

 

 

ü      接口分类

1、查询类接口

查询类接口是指客户端传递一些参数，服务端根据参数依据需求，前往数据库查询需要的结果返回数据的一类接口。

返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。

第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。

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

 

2、操作类接口

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

 

3、上传下载类接口

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

 

4、推送类接口

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

二、接口编写原则

ü      实用性

编写接口API应遵从实用性原则。

1、数据格式：推荐使用JSON格式数据，因为JSON有较好的跨平台性，以及数据格式占用字节数较少，当然也可采用XML、TEXT作为程序开发辅助。

 

2、接口执行效率（接口访问速度）：APP有别于WEB服务，对服务器端要求是比较严格的，在移动端有限的带宽条件下，要求接口响应速度要快，所有在开发过程中尽量选择效率高的框架，PHP推荐使用YAF框架，.NET推荐使用Newtonsoft

 

3、数据量：按需分配，APP客户端需要什么数据就返回什么数据，过多的数据量影响处理速度，最重要的是影响传输效率和浪费用户流量。

 

4、API缓存：这点比较重要，不管是文件缓存还是memcache缓存。

 

 

 

ü      易用性

1、接口、参数命名准确：无论是接口还是参数，命名都应该有意义，让人一目了然。（接口推荐根据APP效果图栏目进行命名）

 

2、一个页面尽可能就用一个接口：现在很多的APP页面都有广告、焦点图、文章列表等，对于这些不同格式的数据，不可能都分配一个接口，这样加大了APP请求接口数，影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端。

 

3、接口数据、状态：接口必须提供明确的数据状态信息，不管是成功的，还是失败的，都必须返回给APP客户端。

4、接口要有可扩展性：方便后期功能性调整，接口应具备可扩展性。

 

 

 

ü      安全性

1、接口安全：目前一般都是在APP客户端和服务器通过约定的算法，对传递的参数值进行验证匹配。但是如果APP程序被反编译，这些约定的算法就会暴露，特别是在安卓APP中，有了算法，完全就可以通过验证模拟接口请求。

 

2、加密规范：在传递用户名密码时，应采用规范的加密算法如MD5、RSA、DES，进行数据通信请求。

 

3、接口版本控制：对于接口版本控制，需要应对不断的APP版本升级，新、旧接口的处理，因而需要关注接口版本控制。

二、接口设计原则

1、尽量减少参数传递：在客户端发起HTTP请求接口操作时，应减少参数传递，如某些操作只需要ID不需要其他参数，这时候就应该只传递ID这个参数。

 

2、尽量避免接口重复性：在客户端APP调用接口时，尽量提高接口复用性，减少HTTP请求，提高程序稳定性。

 

3、数据类型规范：客户端APP调用接口时，应标注参数数据类型，以及是否可为空或者默认字段，如标注了Int型字段，就不能返回“null”的String类型字段，否则容易造成程序APP出现数据类型解析异常。

 

4、设置调用html页面单独列表：调用html页面应标明是否传递安全校验参数，建议表格中采用是或者否单独字段标识。

 

5、编码规范：整个API接口开发过程中，应标注接口编码方式，目前建议采用UTF-8编码，UTF-8通用性以及URL请求方面都较规范。

 

6、请求方式：编写API接口应该标注请求方式，请求方式一般有GET和POST方式

 

7、GET和POST方式：在数量较小情况下可以使用GET方式，但数据量超过1024字节就应该采用POST方式，避免出现请求失败或者请求异常的问题。

 

8、返回接口调用状态：所有API接口都应该统一标识调用的成功失败信息和规范错误编码信息，以及必要的提示字段信息。

 

9、安全机制：接口应规范验证签名机制，用户登录后统一调用KEY对接口安全验证。（关于KEY机制需由接口开发人员定义）

 

10、参数说明：应标注参数名称、是否必选、数据类型及范围、说明以及“否（必选）”传递默认的参数。

 

三、说明文档编写

ü      标注接口调用的统一域名或IP，如：

域名：http://www.XXX.com/

或者IP：http://ip:端口/

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

ü      接口说明，对接口的说明信息，如：

说明：用户登录，获得返回的用户信息。

ü      链接，应采用简写方式，如：

链接：login（这里用的是简写，全部内容是域名加链接，如：http://www.XXX.com/login）

ü      请求方式，应标注GET或POST请求方式。

ü      传递参数，应采用表格形式规范参数说明，如：

参数：

参数	类型	能否为空	备注
Op_code	string(32)	N	帐号
Op_password	string(32)	N aa23	MD5加密后的密码

 

 

ü      返回结果，应采用表格形式规范返回参数说明，如

正常返回结果：

用户登录返回接口
字段	类型	备注
result	int	请求结果，0，失败，1，成功
tip	string	如果失败，此处为失败原因
id	int	用户ID
nickname	string	昵称
birthday	int	出生年份
sex	int	性别，0，女，1，男
address	string	地址
portrait	string	头像，网络路径（域名后的部分）
constellation	int	星座
level	int	等级
experiences	int	经验
gold	int	金币
返回数据示例
{          "result":"1",          "tip":"成功",          "nickname":"飞雪",          "birthday":"1990",          "sex":"0",          "address":"江西 南昌",          "portrait":"upload/20130301121058.jpg",          "constellation":"双子座",          "level":"6",          "experiences":"125",          "gold":"1288"   "statusCode": 1 ,     "statusText": "用户名登录成功！"   }

 

 

 

错误返回结果

用户登录返回接口
statusCode	表示	说明
-999	通用错误	只用于一处，或者无关紧要的提示性，错误
-998	用户名密码错误
-997	用户登陆超时
-996	用户未注册