restful接口规范:就是为了采用不同的后台语言,也能使用同样的接口获取到同样的数据
1、接口详情:
接口url地址
接口说明
2、method请求方式:get、post、delete、put、update等
3、请求参数和返回参数:(请求参数和返回参数都分为:字段、说明、类型、数据格式、是否必填这5列)
字段:属性名
说明:中文释义
类型:属性的类型,只有Undefined、Null、Boolean、String、Number、Object、Array
是否必填:是/否
数据格式:【默认JSON】
请求参数:
分为4种类型:
1)、cookie: 一般用于OAuth认证
2)、request header: 一般用于OAuth认证
3)、请求body数据:
4)、地址栏参数:
² restful 地址栏参数 /v1/products/ID ID为产品编号,获取产品编号为ID的信息
² get方式的查询字段 /v1/products?sortBy=name&order=asc 指定返回结果按照哪个属性排序,以及排序顺序。
返回参数,要分两种情况讨论,接口调用成功或者失败:
code:数据状态码(一般都是前后台约定规则)
常用的code码建议:
200:请求成功
204:请求失败
400:请求报文存在语法错误
500:服务器错误
502:网关出错
503:服务器不可用
504:请求超时
401:没有权限
403:表示对请求资源的访问被服务器拒绝
404:找不到请求的资源
mesage/msg:数据状态信息(一般不仅仅是对数据状态码的解释,更多是对结果的描述,给前台开发者阅读的)
data:数据结果(JSON类型的数据结构)
结构示例:
data: {
code: 200, // 操作成果
data: {} || [], // 数据
message: '请求成果的类似提示语', // 存放响应信息提示【须语义化中文提示】
},
data: {
code: 204, // 操作失败,例如单纯的就是接口调用错误
data: {} || [], // 数据
message: '请求失败的原因', // 存放响应信息提示【须语义化中文提示】
},
4、一致性原则:
1)、前端需要哪些字段,API接口应该返回哪些字段,字段不多也不少。
2)、更新功能尽量做到:初次返回的原始数据参数与提交更新的数据参数结构一致。
3)、时间参数,尽量以一致格式的字符串传递, 如:
‘2019-01’ | ‘2019/01’
‘2019-01-01’ | ‘2019/01/01’
‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
开发中应注意的问题:
1.接口文档在开发的哪个阶段出来:这点是开发效率的主要限制因素。
直接导致的问题是开发前期前端只能做静态页面,中期一直在等后端出文档,如果写完接口才出文档,导致快到提测时间节点上是前端最忙的时候要敲后续的处理数据相关的代码,因为时间比较紧所以先把大概功能处理完就提测,导致测试人员反应前端不细心,细节问题一大堆。
2.字段问绑定的bug:后端出接口文档时每个字段要加字段解释,避免出现前端字段理解不到位而出现字段邦定问题的bug。
3.联调时,前端调用后端接口,发现接口有问题,前端可以提供出错接口调用时传参的字段,但接口具体问题后端应自己解决。
4.数据处理问题:考虑到浏览器的处理能力、带宽限制、安全性因素,数据复杂的处理应后端处理,不能前端能做就给前端,数据处理逻辑都是一样的,后端本来就是处理数据的,后端返回的字段太多或不够,也会影响联调的进度。