前后端对接规范

流程定义

后端编写和维护接口文档，在 API 变化时更新接口文档
后端根据接口文档进行接口开发
前端根据接口文档进行开发 + Eolinker 平台
开发完成后联调和提交测试

graph TD
前后端讨论接口-->后端整理接口文档
后端整理接口文档-->后端接口录入Eolinker接口管理平台
后端接口录入Eolinker接口管理平台-->后端开发服务接口
后端接口录入Eolinker接口管理平台-->前端构建mock服务
后端开发服务接口--> 对接集成
前端构建mock服务--> 对接集成

职责分离

前后端仅仅通过异步接口 (AJAX/JSONP) 来编程
前后端都各自有自己的开发流程，构建工具，测试集合
关注点分离，前后端变得相对独立并松耦合

后端	前端
提供数据	接收数据，返回数据
处理业务逻辑	处理渲染逻辑
Server-side MVC 架构	Client-side MV* 架构
代码跑在服务器上	代码跑在浏览器上

协议规范

GET : 用于从服务器获取资源信息
POST : 用于创建新资源
PUT : 用于完整的替换资源或者创建指定身份的资源
DELETE : 用于删除某个资
PATCH : 用于局部更新资源

返回数据规范

数据格式

正常格式：

需要定义单个数据、集合数据、可能有可能无数据、分页数据、流数据、二进制数据、认证加密数据

异常格式：

异常数据描述格式，包括异常名称、异常发生位置、异常描述

数据编码:

Content-Type: application/json; charset=utf-8

状态码

请求成功状态码标识

200 : 求执行成功并返回相应数据
201 : 创建成功并返回相应资源数据
202 : 接受请求，但无法立即完成创建行为
204 : 请求执行成功，不返回相应资源数据

重定向

301 : 被请求的资源已永久移动到新位置
302 : 请求的资源现在临时从不同的 URI 响应请求
303 : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该使用 GET 方法进行请求
307 : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该保持原有的请求方法进行请求

条件请求

304 : 资源自从上次请求后没有再次发生变化，主要使用场景在于实现数据缓存
409 : 请求操作和资源的当前状态存在冲突。主要使用场景在于实现并发控制
412 : 服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。主要使用场景在于实现并发控制

客户端请求错误

400 : 请求体包含语法错误
401 : 需要验证用户身份
403 : 服务器拒绝执行
404 : 找不到目标资源
405 : 不允许执行目标方法，响应中应该带有 Allow 头，内容为对该资源有效的 HTTP 方法
406 : 服务器不支持客户端请求的内容格式
410 : 被请求的资源已被删除
413 : POST 或者 PUT 请求的消息实体过大
415 : 服务器不支持请求中提交的数据的格式
422 : 请求格式正确，但是由于含有语义错误，无法响应
428 : 要求先决条件，如果想要请求能成功必须满足一些预设的条件要求先决条件，如果想要请求能成功必须满足一些预设的条件

服务端错误

500 : 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理
502 : 作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应
501 : 服务器不支持当前请求所需要的某个功能
503 : 由于临时的服务器维护或者过载，服务器当前无法处理请求

团队约定(标准返回方式)

{
   "code":200, // 1.成功为200， 2.其他非200
    "data": {
        "id":"1001",
        "name":"张三",
        "age":"20"
    },
    "msg":"成功", //  1.成功信息， 2其他返回对应信息 
}

URL规范

GET https//domain.com/api/模块名/菜单名/接口名/:param

不能使用大写，用中横线 - 不用下划线 _ ；
使用名词表示资源集合，使用复数形式（为确保所有API URIs保持一致），不能使用动词；
每个资源都至少有一个标识它的URI，同时应该遵循一个可预测的层次结构来提高可理解性，从而提高可用性；
无需在URI中增加版本号，通过HTTP请求头信息的字段中进行区分（或者在URI包含主版本信息，同时请求头包含子版本信息。

本篇文章由一文多发平台ArtiPub自动发布