前言
本文的主要初衷就是规范约定先行，尽量避免沟通联调产生的不必要的问题，让大家身心愉快地专注于各自擅长的领域。前端开发负责页面的展示、交互体验越来越灵活、炫丽，响应体验也要求越来越高。后端开发负责服务的高并发、高可用、高性能、高扩展等特性。随着开发需求高度的提示，开发难度愈加苛刻，从而导致前后端研发各自专注于自己擅长，让专业的人做专业的事。
开发流程
- 后端编写和维护接口文档，在 API 变化时更新接口文档
- 后端根据接口文档进行接口开发
- 前端根据接口文档进行开发 + Mock平台
- 开发完成后联调和提交测试
开发实施
- 接口文档服务器：可实现接口变更实时同步给前端展示。
- Mock接口数据平台：可实现接口变更实时Mock数据给前端使用。
- 接口规范定义：很重要，接口定义的好坏直接影响到前端的工作量和实现逻辑。
以极客Mock为例，Mock规范如下：
a.请求类型，默认POST
b.请求参数需包含：参数名、参数类型、是否必填、描述（如有必要需备注如何获取相关参数）、示例
c.返回示例需包含：code和data，其中data的参数名应为英文，需有对应注释的中文
d.浮动注释需包含：全局code和公共参数的注释
接口规范V1.0.0
一、规范原则
- 接口返回数据即显示：前端仅做渲染逻辑处理；
- 渲染逻辑尽量避免跨多个接口调用；
- 前端关注交互、渲染逻辑，尽量避免业务逻辑处理的出现；
- 请求响应传输数据格式：JSON，JSON数据尽量简单轻量，避免多级JSON的出现；
二、基本格式
2.1请求基本格式
a.GET请求：xxx/login?key1=value1&key2=value2
b.POST请求：xxx/login?key1=value1&key2=value2
2.2响应基本格式
{
code: 200,
data: {
message: "success"
}
}
//code: 请求处理状态
//200：请求处理成功
//500: 请求处理失败
//401: 请求未认证，跳转登录页
//406: 请求未授权，跳转未授权提示页
2.3响应列表和分页格式
{
code: 200,
data: {
recordCount: 2,
message: "success",
totalCount: 2,
pageNo: 1,
pageSize: 10,
list: [
{
id: 1,
name: "XXX",
code: "H001"
},
{
id: 2,
name: "XXX",
code: "H001"
} ],
totalPage: 1
}
}
//a.data.recordCount: 当前页记录数
//b.data.totalCount: 总记录数
//c.data.pageNo: 当前页码
//d.data.pageSize: 每页大小
//e.data.totalPage: 总页数
三、特殊内容规范
3.1下拉框、复选框、单选框
由后端接口统一逻辑判定是否选中，通过isSelect标示是否选中，示例如下：
{
code: 200,
data: {
message: "success",
list: [{
id: 1,
name: "XXX",
code: "XXX",
isSelect: 1
}, {
id: 1,
name: "XXX",
code: "XXX",
isSelect: 0
}]
}
}
禁止下拉框、复选框、单选框判定选中逻辑由前端来处理，统一由后端逻辑判定选中返回给前端展示；
3.2 Boolean类型
关于Boolean类型，JSON数据传输中一律使用1/0来标示，1为是/True，0为否/False；
3.3 日期类型
关于日期类型，JSON数据传输中一律使用字符串，具体日期格式因业务而定。
