接口设计---更好的提高效率

接口设计规范

一. 接口示例

以下是一个用户信息接口的文档示例，包含接口描述，请求参数，响应参数，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”
}
}

二. 基本规范

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

原则：在以下命名规范的基础上尽量保持良好的可读性，见名知意。另外这里需要额外提下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确认。

object类型数据

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

// model.java
public class Model {
     public String name;
     public String age;
} 

array类型数据，正常情况下在解析json的时候，1.先解析code和msg，判断code==200的情况下继续解析data。2.将data下面的json串解析成当次请求需要的model数据结构。对于array类型的数据，即使只有1个list字段，也要保证data下是个完整的object结构，这样我们在用Gson解析model的时候，统一将data层级下的数据当object解析就可以了，不用区分object或array的情况。