后端开发接口规范

因不同人员的开发习惯不同，造成前后端连调时许多问题要重复确认。也会出现因前后端人员对

默认值的期望不同而造成的代码缺陷。因此制定本接口规范，规范前后端的开发标准。

 
参考如下接口文档格式：

接口名称：审核列表

接口描述：接口的使用场景

接口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