接口设计规范

接口设计规范

接口规范化以后，会少很多坑，避免自己下次再遇到。

1 接口示例

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

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 基本规范

2.1 公共参数

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，用于统计或其他用途，放在header或url参数中。例如

字段名称	说明
version	客户端版本。1.0.0
token	登录令牌
os	手机系统版本。12
from	请求来源。android/ios/h5
screen	手机尺寸。1080*1920
model	机型。IPhone7
net	网络状态。wifi

2.2 响应数据

响应数据统一格式：code、msg、data。

array类型数据。通过list字段，保证data的Object结构。

分页类型数据。返回总条数，用于判断是否可以加载更多。

扫描二维码关注公众号，回复： 4415282 查看本文章

// object类型数据
{
    "code":1,
    "msg":"成功",
    "data":{}
}
// array类型数据。
{
    "code":1,
    "msg":"成功",
    "data":{
        "list":[]
    }
}
// 分页类型数据。
{
    "code":1,
    "msg":"成功",
    "data":{
        "list":[]
        "total":"10"
    }
}

列表类数据接口，无论是否要求分页，最好支持分页，pageSize=Integer.Max即可。

2.3 字段类型规范

统一使用String类型。某些情况，统一使用String可以防止解析失败，减少类型转化操作。

Boolean类型，1是0否。客户端处理时，非1都是false。

if("1".equals(isVip)){
    
}else{
    
}

status类型字段，从1+开始，区别Boolean的0和1。“0”有两种含义，（1）Boolean类型的false，（2）默认的status

2.4 上传/下载

上传/下载，参数增加文件md5，用于完整性校验（传输过程可能丢失数据）。

2.5 避免精度丢失

缩小单位保存数据，如：钱以分为单位、距离以米为单位。

3 瘦客户端

客户端尽量不处理逻辑

客户端不处理金额

客户端参数校验规则可以通过接口返回，同时提供默认规则，接口不通则使用默认规则。

4 拓展性

图片文案等，与校验规则类似，通过接口返回，并提供默认。

列表界面

// 静态列表
{
    "name": "张三",
    "sex": "男",
    "age": "20岁",
    "nickName": "小张"
}
// 动态列表
{
    "userInfos":[
    {
        "key":"姓名",
        "value":"张三"
    },{
        "key":"性别",
        "value":"男"
    },{
        "key":"年龄",
        "value":"20岁"
    },{
        "key":"昵称",
        "value":"小张"
    }]
}

多个boolean可以flag替换

{
    "flag":"7" // 二进制：111，三位分别表示三个boolean字段
}

long flag = 7;
System.out.println("bit="+Long.toBinaryString(flag));
System.out.println("第一位="+((flag&1)==1));
System.out.println("第二位="+((flag&2)==1));
System.out.println("第三位="+((flag&4)==1));

5 安全性

so层，不懂

6 兼容性

区分版本

7 性能优化

合并接口。一个页面一个接口

字段简写

无用字段清理

图片裁剪

局部刷新。页面需要的数据，可以用前一个页面带来。

预加载