API规范

31 篇文章 23 订阅
2 篇文章 0 订阅

通用要求
接口命名小驼峰
如果不是restfull的接口,需要语义化,例如:getUserInfo、getUserList、createUser、updateUser、deleteUser、uploadUserImg
接口尽量轻巧,前端不需要的数据,不需要返回
后端尽量统一风格,禁止单独适配
为了避免某些Chrome浏览器广告屏蔽插件的误拦截,不使用ad等广告字眼

对前端的要求:前端使用axios统一封装请求方法,做统一请求、拦截

安全性要求
如果是客户敏感信息,接口绝对需要返回最小量的数据
需要进行数据脱敏的情况,由后端进行脱敏,不能仅靠前端来脱敏展示
提交订单类接口,后端不能相信前端传入的金额数据,需要自己计算

接口的部署
接口统一部署在网关上,相关后端同学来维护发布

接口文档维护
统一维护在yapi平台上,禁止其余方式传输,一切以yapi平台为准;接口的变更,也需要同步在yapi平台上
接口文档,字段需要有必要的中文描述,以及枚举值

通用接口返回体
{
“code”:“200”, // 状态码,200-正常;401-未登录,前端控制跳转登录界面
“data”:{ // 数据返回体
},
“message”:“成功” // 提示信息,如果code不是200的话,前端将此提示信息弹窗展示
}

code枚举
200:正常
401:未登录,前端控制跳转登录界面
403:无权限,前端跳转相应界面

data 字段返回需要完整,禁止字段返回缺失
例如

data: {
name: ‘’, // 空字符串
obj: null, // 空对象
totol: 0, // 无值的数字
list: [] // 空数组
}

message
如果code返回不是200,则前端弹窗提示message,需要简单醒目,不能抛出 Java的堆栈报错信息
如果code返回正确,message也尽量返回正确信息,用于前后端对比

前端通用组件要求
前端基于目前的业务,封装了一些公用列表、弹窗、交互、数据脱敏等一系列通用组件,需要后端的同一类接口,进行method、请求格式、返回格式的统一

例如:

获取列表的接口,post方式
通过id获取单个数据项的信息时,使用restfull的get格式,如 /person/123
添加类接口,post方式;更新类接口,put方式;删除类接口,delete方式
列表分页请求,通用参数
page: 当前页码,以1开始
size:当前页面展示的条数,前端默认10

总之,不能出现分页信息,传入后端需要的start+limit的那种数据库查询的方式

列表返回的格式
需要返回 total 总条数,前端用于分页
不需要返回总页数之类的信息

{
“code”:“200”, // 状态码
“data”:{
“records”:[ // 数据list

    ],
    "total":20 // 总条数
},
"message":"成功" // 提示信息,如果code不是200的话,前端将此提示信息弹窗展示

}

日期格式传输
前后端传输时间字段,均以13位标准时间戳传输

布尔类数据
统一使用1、0来传输数据,1为true,0为false

超长型数字
后端库表的id,可能生成时超过16位,此时会面临精度丢失问题,这种情况,需要将id,通过字符串的形式传回到前端

数据精度处理
为了避免出现那种0.1+0.2=0.30000000000000004的问题,通常情况下,前端不做计算后结果的传输,一切计算后的数据,均由后端来计算
电商订单类,更应当如此!!!
后端返回前端数据,数据精度也需要过滤校验

图片地址的返回
需要返回全量的oss图片地址,禁止前端拿到url后再行拼接https

post方式请求细节
Content-Type的选择
除了上传类的post请求使用multipart/form-data外,其余的post请求,均使用application/json格式

post方式,尽量避免通过url上传值,统一放在body里面

模糊搜索接口约定
模糊搜索,要求速度快,数据量少

请求方式:get

接口返回:无需分页,最多返回10条数据

如无特殊规定,模糊搜索接口返回数组格式,格式如下

{
“code”:“200”, // 状态码
“data”: [{
value: 1
label: ‘已创建’
}, {
value: 2
label: ‘部分完成’
}],
“message”:“成功” // 提示信息,如果code不是200的话,前端将此提示信息弹窗展示
}

后发先至接口的处理
有的时候,接口调用比较密集,而前端拿到返回需要有次序,此时需要后端在返回体内,添加前端开始调用接口的时间戳,用于前端来判断接口前后顺序

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

QY’UniverseSpace

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值