前后端分离规范

• 前后端分离规范原则
  1. 规范原则

1. 后端仅开发接口、处理业务逻辑、提供数据；
2. 前端关注交互，调用接口仅做渲染逻辑处理，尽量避免业务逻辑的处理；
3. 前端渲染逻辑禁止跨多个接口调用；
4. 前后端都各自有自己的开发流程，构建工具，测试集合；
5. 前后端关注点分离，相对独立并松耦合。
   1. 开发流程

1. 后端编写维护接口文档，每个接口的维护包括接口作用、接口路径、请求类型、入参、出参、示例等，并在文档顶部或底部维护接口返回状态码和状态码含义；
2. 后端在接口有变动时要及时更新接口文档；
3. 后端根据接口文档进行接口开发，开发完成可以利用接口规范工具如postman、eolinker进行自测；
4. 前端根据接口文档进行前端开发，可以利用Mock平台构造虚拟数据进行界面渲染；
5. 开发完成后前后端进行接口联调，联调完毕提交测试人员测试。

• Restful接口规范
•     URI命名规范

任何事务，只要有被引用到的必要、就是一个资源，每一个资源都有一个唯一的URI（统一资源定位符），URI表述具有可寻址性、具有自描述性。

使用“/”表示资源的层级关系

如：/stops/clothess/jackets 表示 商店/衣服/上衣，但/不要在末尾处。

使用“-”增强URI的可读性

如：/clothes-shops/jackets/short-sleeves 表示 服装店/上衣/短袖。

​​​​​​​使用“？”来过滤资源

/clothes-shops/jackets/short-sleeves?color=红色&page=1&pageSize=10。

使用/表示资源层级时层次不宜过深，3到5层即可，可以使用？查询参数代理实体导航，如/streets/3/clothes-shops/2/jackets/short-sleeves/1（id为3的街道下id为2的服装店中的上衣中id为1的短袖）;

可以使用Get  /jackets/short-sleeves?streetId=3&shopId=2&sleeveId=1来代替。

​​​​​​​使用名词

URI只应该用来表示资源的名称，而不应该包含资源的操作，所以URI里面应该用名词来表述，而不应该使用动词来描述，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"，所以API中的名词也应该使用复数。

比如获取一件衣服信息：要用/clothes-shops/jackets/short-sleeves/ID来表述，不要用/clothes-shops/jackets/getShortSleeveInfo?id=xxx这种方式来表述。

​​​​​​​使用http method来对应不同的请求

    GET（SELECT）：从服务器取出资源（一项或多项）

Get  /street/clothes-shops?streetId=1 查出街道1所有服装店

Get  /street/clothes-shops/Id?streetId=1  查出街道1指定id的服装店

     POST（CREATE）：在服务器新建一个资源。

POST /street/clothes-shops?streetId=1 在街道1新建一个服装店

    PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

PUT  /street/clothes-shops/Id?streetId=1 更新街道1指定id的服装店信息（客户端提供服装店所有信息）

    PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

PATCH  /street/clothes-shops/Id?streetId=1 更新街道1指定id的服装店信息（客户端提供服装店部分信息）

    DELETE（DELETE）：从服务器删除资源。

DELETE  /street/clothes-shops/Id?streetId=1 删除街道1指定id的服装店信息

​​​​​​​接口返回规范

接口返回使用自定义的Response类；如

​​​​​​​返回码status规范

接口成功返回200时或者302跳转时status返回success，否则返回faild，用于前端判断提示信息的显示

返回code、message规范

1. 接口调用正常code返回200，message返回成功；
2. 接口需要重定向code返回302，message返回重定向；
3. 接口异常时code和message的返回：

4. API 可能抛出两类异常：业务异常和非业务异常。业务异常由自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则冲突等，比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误等等。

   业务类异常通常自定义code和message，code尽量使用http规范里的错误码表示，message返回的信息尽量表明业务类异常的原因，http常用异常请点击：http规范常用异常表示；

常用的http状态码及使用场景：

状态码	使用场景
400 bad request	常用在参数校验
401 unauthorized	未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication 和 authorization 的区别）
403 forbidden	无权限
404 not found	资源不存在
500 internal server error	非业务类异常
503 service unavaliable	由容器抛出，自己的代码不要抛这个异常

code返回500表示非业务类异常，mesage统一返回“服务器端错误，请稍后再试”。

​​​​​​​返回result规范

1. 针对不同的http method请求操作的result的返回:

http method请求类型	result返回
GET	单个对象、集合
POST	新增成功的对象
PUT/PATCH	更新成功的对象
DELETE	空

1. 单个对象使用json格式，集合使用json数组格式；

Json格式的规范：

1. 时间用时间戳或是“yyyy-MM-dd HH:mm:ss”这种格式；
2. Boolean类型，JSON数据传输中一律使用1/0来标示，1为是/True，0为否/False；
3. 返回的对象里面如果某个字段没有值的话也要用null来表示，而不能对象里没有该字段；
4. 返回的集合如果没有值用空数组表示；
5. Json数据尽量简单轻量，尽量避免多级json；

1. 分页的情况

    返回的result需要分页的表示如下：

result:{

    "paging":{"limit":10,"page":0,"total":729},

    "data":[{},{},{}...]

}