1

前言

   

 

兵马未动，粮草先行。在一款APP产品的各个版本迭代中，兵马的启动指的是真正开始敲代码的时候，粮草先行则是指前期的需求，交互，UI等评审准备阶段，还有本文要说的接口的设计与评审。

 

虽然很多时候一个api接口的业务，数据逻辑是后端提供的，但真正使用这个接口的是客户端，一个前端功能的实现流程与逻辑，有时候只有客户端的RD才清楚，从某种意义来说，客户端算是接口的需求方。

 

所以建议在前期接口设计和评审时，客户端的RD应该更多的思考和参与，什么时机调什么接口？每个接口需要哪些字段？数据含义怎么给？只有这些都考虑清楚，且达成一致并产出接口文档后，当项目真正启动时，根据接口协议进行开发，才能尽量避免各种不确定因素对项目整体进度的影响。

 

本文介绍了接口设计中常见的规范，以及个人的一些思考与总结，水平有限，权当是抛砖引玉，如果有更好的设计，请在文章下方留言告诉我，谢谢。

 

 

2

接口设计规范

   

一. 接口示例

 

以下是一个用户信息接口的文档示例，包含接口描述，请求参数，响应参数，json示例等。

 

接口描述：用户登陆成功后，或进入个人中心时会获取一次用户信息

 

URI	方法
/userinfo	GET

 

请求参数

 

名称	必填	备注
id	是	用户id

 

响应参数

 

名称	类型	备注
id	String	用户id
name	String	姓名，例：张三
age	String	年龄，例：20

 

json示例

{
"code":200,
"msg":"成功",
"time":"1482213602000",
"data": {
    "id":"1001",
    "name":"张三",
    "age":"20"
}}

2

基本规范

   

1.通用请求参数

 

每个请求都要携带的参数，用于描述每个请求的基本信息，后端可以通过这些字段进行接口统计，或APP终端设备的统计，一般放到header或url参数中。

 

字段名称	说明
version	客户端版本version，例：1.0.0
token	登陆成功后，server返回的登陆令牌token
os	手机系统版本（Build.VERSION.RELEAS）例：4.4，4.5
from	请求来源，例：android/ios/h5
screen	手机尺寸，例：1080*1920
model	机型信息（Build.MODEL），例：Redmi Note 3
channel	渠道信息，例：com.wandoujia
net	APP当前网络状态，例：wifi，mobile；部分接口可以根据用户当前的网络状态，下发不同数据策略，如：wifi则返回高清图，mobile情况则返回缩略图
appid	APP唯一标识，有的公司一套server服务多款APP时，需要区分开每个APP来源

 

2.请求Path，http://www.online.com/api/ [path]

 

原则：在以下命名规范的基础上尽量保持良好的可读性，见名知意。另外这里需要额外提下restful规范，个人理解restful规范是通过path表示当前请求的资源，通过method表示当前请求的操作动作（post=增，delete=删，put=改，get=查），例：GET /userinfo/{id}，通过这个path就可以清楚的知道当前请求的意图是根据id获取用户信息，而APP开发中很多时候一个页面是需要同时获取，如，用户，订单，营销各种信息，这时候就很难用一个path来表示当前请求的真正意图，restful规范就很难得到实现，有不同见解的欢迎交流。故本文介绍的接口设计方法，只区分get和post，通过path命名定义请求行为，

 

操作行为	Method	Path
查找	GET	getXxx
增加	POST	addXxx/submitXxx
修改	POST	modifyXxx
删除	POST	delXxx

 

示例

 

操作行为	Method	Path
获取用户信息	GET	getUserInfo
增加收货地址	POST	addAddress
修改密码	POST	modifyPwd
删除收货地址	POST	delAddress
登陆	GET	login
发送短信验证码	GET	sendSms
订单支付	POST	orderPay

 

3.响应数据

 

字段名称	说明
code	响应状态码，200：成功；非200：失败
msg	请求失败时的message
time	服务端时间戳，单位：毫秒。用于同步时间
data	数据实体

 

code=200时，msg=登陆成功/修改成功/提交成功；如果需要Toast，可以直接使用msg。

code!=200时，msg=错误提示信息；比如login接口，"账号或密码错误"，"账号不存在"类似这些的业务提示文案放在msg字段，客户端直接Toast就可以了。不过需要提醒后端同学，错误提示不能自己觉的什么合适就提示什么，要按需求文档来提供，或和PM确认。