SRM移动开发接口规范

简介

由于目前SRM移动应用API接口返回的的格式比较混乱，为了能够是确保API接口统一规范，定义以下规范，编写是为了APP开发人员快速定位需要的接口信息，使开发人员在最短的时间内找到需要的接口，同时也会对编写API接口人员后期的维护修改提高效率。

(一) 接口分类

一、查询类接口

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

二、操作类接口

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

三、上传下载类接口

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

（二）接口编写原则

（一）实用性

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

1、数据格式：

推荐使用JSON格式数据，因为JSON有较好的跨平台性，以及数据格式占用字节数较少。

2、接口执行效率（接口访问速度）：

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

3、数据量：

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

4、API缓存：

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

（二）易用性

1、接口、

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

2、一个页面尽可能就用一个接口：

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

3、接口数据、状态：

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

4、接口要有可扩展性：

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

（三）安全性

1、接口安全：

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

2、加密规范：

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

3、接口版本控制：

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

（三）接口编写原则、接口设计原则

1、尽量减少参数传递：

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

2、尽量避免接口重复性：

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

3、数据类型规范：

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

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

5、请求方式：

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

6、GET和POST方式：

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

7、返回接口调用状态：

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

8、安全机制：

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

9、参数说明：

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

(四）、说明文档编写

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

1.查询类接口

.返回单条信息场景

ü      接口说明，对接口的说明信息，如：
说明：用户登录，获得返回的用户信息。
ü      请求的地址：XXXX
ü      请求方式，应标注GET或POST请求方式。
ü      传递参数，应采用表格形式规范参数说明，如：

image.png

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

正常返回结果：

{
         "errcode":"0",
         "errmsg":"成功",
         "id":30 
}
##错误结果
{
         "errcode":"-999",
         "errmsg":"false"
}

.返回多条信息场景