接口定义备忘录

接口规范的意义

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

接口分类

（一）查询类接口

查询类接口是指客户端传递一些参数，服务端根据参数依据需求，前往数据库查询需要的结果返回数据的一类接口。返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。
a.第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。
b.第二种比如获取客户，客户端把用户的身份信息上传到接口，服务器返回此身份下的所有客户数组集合。

（二）操作类接口

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

（三）上传下载类接口

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

（四）推送类接口

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

接口编写原则

（一）实用性

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

2．接口响应时间：APP有别于WEB服务，对服务器端要求是比较严格的，在移动端有限的带宽条件下，要求接口响应速度要快，所有在开发过程中尽量选择效率高的框架。

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

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

（二）易用性

1．接口、参数命名准确：论是接口还是参数，命名都应该有意义，让人一目了然。

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

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

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

（三）安全性

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

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

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

4．时间戳：接口请求和响应都加时间戳，通过对时间戳的验证，可以一定程度上防止重放攻击。

接口设计原则

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机制需由接口开发人员定义），对于安全系数要求较高的接口应该使用HTTPS请求，比如支付接口，订单接口，用户信息接口。

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

文档编写规范

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

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

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

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

4．数据类型：基本数据类型，如下图。

5．符号定义：强制域、条件域和选用域，如下图。

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

7．系统响应参数：响应码、响应消息和业务数据，如下图表。

8．业务接口描述信息：接口名称、接口描述、请求方式、测试地址、生产地址、备注。
      参数说明：参数名、含义、类型、长度、必填、备注。
      参数格式：请求参数格式、响应参数格式。

8．常见响应码：约定的常见系统错误码，如下图。