一、前言

随着互联网的高速发展，前端页面的展示、交互体验越来越灵活、炫丽，响应体验也要求越来越高，后端服务的高并发、高可用、高性能、高扩展等特性的要求也愈加苛刻，从而导致前后端研发各自专注于自己擅长的领域深耕细作。

然而带来的另一个问题：前后端的对接界面双方却关注甚少，没有任何接口约定规范情况下各自撸起袖子就是干，导致我们在产品项目开发过程中，前后端的接口联调对接
工作量占比在30%-50%左右，甚至会更高。往往前后端接口联调对接及系统间的联调对接都是整个产品项目研发的软肋。

本文的主要初衷就是规范约定先行，尽量避免沟通联调产生的不必要的问题，让大家身心愉快地专注于各自擅长的领域。

后端 (JAVA)，专注于
服务层
数据格式、数据持久化
业务逻辑
前端，专注于
UI层
控只逻辑、渲染逻辑
交互、用户体验

几点优势：

关注点分离
职责分离
对的人做对的事
更好的共建模式
快速的反应变化

二、开发流程

后端编写和维护接口文档，在 API 变化时更新接口文档
后端根据接口文档进行接口开发
前端根据接口文档进行开发 + Mock平台
开发完成后联调和提交测试
Mock 服务器根据接口文档自动生成 Mock 数据，实现了接口文档即API：

三、具体实施

现在已基本完成了，接口方面的实施：

接口文档服务器：doclever - 可实现接口变更实时同步给前端展示；（doclever.mytijian.cn）
Mock接口数据平台：可实现接口变更实时Mock数据给前端使用；
前后端都有责任监督和规范接口定义，大家互相纠正不符合规范的接口。

四、规范原则

接口返回数据即显示：前端仅做渲染逻辑处理；
渲染逻辑禁止跨多个接口调用；
前端关注交互、渲染逻辑，尽量避免业务逻辑处理的出现；
请求响应传输数据格式：JSON，JSON数据尽量简单轻量，避免多级JSON的出现；

五、请求基本格式

由于我们的系统会运行在各体检中心的内部网络上。有的体检中心网络限制了PUT、DELETE等请求方式。
所以请求方式只允许使用 《GET、POST》 两种方式

GET请求参数：

1. 参数使用"?"方式(?attr=val)跟在url之后
2. 不允许使用"/"方式(/val)传参

POST请求参数：

1. 若使用post，参数必须全部写在请求body中
2. 不允许再以"?"或者"/"的方式再在url中带请求参数
3. 只以json 和form-data的形式交互，比如上传文件可使用form-data，一般情况使用json

栗子：

action结构： product/action (资源/操作)

资源采用名词命名, e.g: 产品 -> meal
新增资源, e.g: 新增产品, url -> /meal/save , verb -> POST
修改资源, e.g: 修改产品, url -> /meal/update , verb -> POST
资源详情, e.g: 指定产品详情, url -> /meal?id={id} , verb -> GET
删除资源, e.g: 删除产品, url -> /meal/delete?id={id} , verb -> GET
资源列表, e.g: 产品列表, url -> /meal/list , verb -> GET
资源关联关系, e.g: 关联产品, url -> /meal/link , verb -> POST
资源关联关系, e.g: 解除关联产品, url -> /meal/unlink , verb -> GET

六、响应基本格式

响应数据

业务处理成功响应数据格式

响应数据必须是标准JSON格式{}或[]，例如：

对象数据结构
```
{
  userName:"zhangsan",
  age:25
  }
```

列表数据结构

[
      {
          userName:"zhangsan",
          age:25
      },
      {
          userName:"zhangsan",
          age:25
      }
  ]

业务处理失败响应数据格式


{
    code: 错误编码,
    text: 错误描述
}

返回具体数据

前端确定使用到的字段，后端必须返回该属性，不可缺省

Http状态码

系统状态码
200: 业务处理成功
400: 业务处理失败或系统异常
服务器状态码
500：服务器错误
50*: 其他服务器错误

系统通用异常编码

EX_1_2_sys_02_01_001：未登录
EX_1_2_sys_02_02_001：未授权

异常码含义：

e.g EX_1_2_sys_02_01_001

EX：Exception缩写，表示异常
1：表示异常类型（0：系统异常，1：业务异常）
0：表示日志级别（0：error，1：warn，2：info）
sys：模块名称
01：子模块序号
01：业务场景序号，例如，01：未登录

七、doclever

http://doclever.mytijian.cn/

1. 注册账号

注册账号

2. get

3. post

4. mock

参见附件

附件

DOClever使用帮助手册.pdf

文档更新时间: 2019-07-22 09:54

前后端接口规范