接口规范纪要

HTTP请求一般采用GET 和 POST:

• GET 请求参数格式为Key=Value
• POST请求参数格式为JSON

响应数据格式

{
    "code": 0,   // 0为成功 | 小于0为失败 | 大于0为成功且其他某种状态
    "message": "失败原因",
    "data": null // 数据 为空时为null 
}

• 成功:

{
    "code": 0, 
    "message": "请求成功",
    "data": { 
        "name": "LEE",
        "age": 27
     } 
}

• 失败:

{
    "code": -9999, 
    "message": "身份鉴权无效"
}

其他个例

时间数据类型 使用毫秒单位时间戳 (整型)

• 建议:

{
    "time": 153442323000    // ms
}

金额数据类型 使用分单位 (整型)

• 建议:

{
    "price": 1200    // 12元 = 1200分
}

是与否数据类型 使用0或1 (整型)

• 不建议:

{
    "isVip": 0 
}

• 建议:

{
    "vip": 0    // 0: 不是会员, 1: 是会员 
}

状态(State)或类型(Type)数据类型 使用1, 2, 3, 4... (整型)

• 建议:

{
    "state": 1,    // 1: xxx, 2: xxx, 3: xxx
    "type": 2      // 1: xxx, 2: xxx, 3: xxx
}

数组数据类型 为空则使用 []

• 不建议:

{
    "list": null 
}

• 建议:

{
    "list": [] 
}

字段命名遵循驼峰命名法, 且不进行冗余命名. 例如:

• 不建议:

{ 
    "xxxx": 1,
    "xxxx": "xxxx",
    "xxx_xxxx_xx": "xxx",
    "video": {
        "videoCode": "xxxx",
        "videoName": "xxxx",
        "videoImage": "xxxx"
    }
}

• 建议:

{ 
    "xxxx": 1,
    "xxxx": "xxxx",
    "video": {
        "code": "xxxx",
        "name": "xxxx",
        "image": "xxxx"
    }
}

字段命名保持统一风格, 相同类型或含义的字段名风格保持统一

• 不建议:

{ 
    "xxImg":"xxx",
    "xxPic":"xxx",
    "xxImage":"xxx",
    "xxPicture":"xxx",
    "xxPhoto": "xx",
    "xxImgUrl": "xx",
    "xxPicURL": "xx"
    
    "xxNum": 0,
    "xxCount": 0,
    "xxNumber": 0
}

所有可能为null 或者可能不存在的字段需在文档中用注释标明 (不标注的默认认为不会为空)

• 建议:

{ 
    "xxxx": 1,
    "xxxx": "xxxx",        
    "video": {             
        "code": "xxxx",    
        "name": "xxxx",    // 无xx时为空字符串
        "image": "xxxx"    // 无xx时为null
    },
    "list": []
}

个数 数量的数据类型使用整型

• 不建议:

{ 
    "xxCount": "122",
    "xxNumber": "2333"
}

• 建议:

{ 
    "xxCount": 122,
    "xxNumber": 2333
}

百分比数据类型使用整型

• 建议:

{
    "progress": 98    // 进度百分比 0 - 100 
}