因不同人员的开发习惯不同，造成前后端连调时许多问题要重复确认。也会出现因前后端人员对
默认值的期望不同而造成的代码缺陷。因此制定本接口规范，规范前后端的开发标准。
参考如下接口文档格式：
接口名称：审核列表
接口描述：接口的使用场景
接口URL： {service}/rider/check/r/new/list
请求方式：get|post
请求参数（json对象）// 可以根据需要让后端说明接受的是params还是model
数据格式：{key1: value1, key2: value2, ...}
参数名
数据类型
是否必填
取值范围
含义
checked
int
是
(0,10)
审核状态
userName
string
否
[0, 10]
用户名
userPhone
string
否
手机号
orgId
int
否
组织ID
cityId
int
否
城市ID
orgType
int
否
组织类型
pageNum
int
否
页码号
pageSize
int
否
每页数据
返回结果
1、返回结果要求是json对象
2、数据格式：{code: 0, msg: "ok", data: {model:{}}} // 真实数据最好放在data内部，前端统一从data里面获取
3、返回数据字段，都要有字段描述，明确告知前端字段的作用，如下注释内容
{
"code": 0,
"msg": "成功",
"data": {
"list": [{
"accountId": 0, // 账号ID
"accountSource": 0, // 账号来源
"bmOrgId": 80, // 组织ID
"bmRoleCode": 0, // 角色Code
"bmUserId": 112, // bmID
"cardNo": "140***********5811", // 身份证号
"cardNoChanged": false, // 身份证是否修改
"checked": 0, // 审核状态
"ctime": "2018-03-26 19:54:55", // 创建时间
"faceUrlChanged": false, // 头像是否修改
"gender": 0, // 性别 0:男，1:女
"genderChanged": false, // 性别是否改变
"headPortraitUrlChanged": false, // 用户头像是否改变
"healthCertificateDateChanged": false, // 健康证日期是否改变
"healthCertificateFaceUrlChanged": false, // 健康证头像是否改变
"healthCertificateType": 0, // 健康证类型
"healthCertificateTypeChanged": false, // 健康证类型是否改变
"healthCertificateUrlChanged": false, // 健康证图片是否改变
"id": 111, // 唯一标识
"idCardUrlChanged": false, // 身份证图片是否改变
"isCheckHealthCertificate": 0, // 是否校验健康证
"jobType": 0, // 工作类型
"mobile": "140****1112", // 电话
"name": "姓名", // 姓名
"nameChanged": false, // 名字是否改变
"opUserId": 0, // 操作人ID
"opUserType": 0, // 操作人类型
"orgName": "加盟站", // 组织名称
"orgType": 0, // 组织类型
"orgTypeName": "自营", // 组织类型名称
"originOrgId": 0, // 源组织ID
"utime": "2018-03-26 19:54:55", // 最近更新时间
"valid": 0 // 是否有效
}],
"pageNo": 10,
"pageSize": 20,
"totalCount": 2000
}
}
4、数据直接可用，不用前端二次加工（如排序、计算）
5、列表展示数据如果包含字典类型数据，需要后端直接给出展示名称（前端不做映射处理）
6、按需给出所需字段，尽可能去掉前端不需要的多余字段
7、对于各种字段类型，如果不存在必须返回该字段，缺省值如下
类型
缺省值
Array
[ ] // 空数组
String
'' // 空串
Number
null
Json 对象
null
linux时间戳
0
8、对于 复杂的数据类型，比如 result: {a: '字段1', b: '字段2' }, 假如 result为空，则返回 result: null，而不是 result : { a: '', b: ''}
分页约定：
1、请求从第一页开始、即pageNumber 从1开始
2、后端需返回 pageCount(本次查询返回多少条记录), totalPage（总页数）。
原文链接：https://blog.csdn.net/qq_22010473/article/details/90473372