前后端分离接口规范总结
一、概述
后端开发很多时候都要写接口,良好的接口命名规范,编码规整,高效有序,可以明显提高工作质量,进而提高工作效率。
二、具体规范
接口开发包括提供给管理端接口,前端APP接口,H5页面接口,第三方接口。
2.1、规范原则
分离明确:后端处理所有的业务逻辑,前端仅接受数据,做页面渲染。
2.2、参数规则
包装类参数:参数类型尽量定义成包装类,以免前端传空报错。
2.3、内容规则
代码精炼:在保证拓展性的情况下,尽量做到代码精简。比如判空操作能够sql查询判空就尽量用SQL查询判空,就不用在代码里面判断空了。使用工具类代替原生方法,比如参数拼接可以使用工具类HttpUtil.toParams(params)代替。
内容规整:有数字的地方尽量使用枚举类代替,因为使用枚举类能够明确表述该数字代表的含义,便于阅读。循环时尽量用增强for循环,可以减少判空操作。
代码质量与性能:
必要注释:在关键代码出编写必要的注释,有利于后期迭代与更新。
包装类结果:
状态码:0-表示失败,1-表示成功
接口返回信息描述:msg为结果提示信息,如果APP的话就可以返回给用户提示。
接口返回数据:返回数据对象,通常是实体类对象,VO
{
"code": "1",
"msg": "查询成功",
"data": {
"id": 1,
"webServicePhone": "028-80000000",
"webServiceQq": "123456789",
"webServiceMail": "yoli_tin@163.com",
"companyName": "华盛集团",
"companyAddress": "天府二街",
},
"success": true
}
异常处理:
捕获异常:写的接口基本都要捕获异常。
抛出运行时异常:有的异常信息不需要系统处理或者直接需要反馈给用户的信息,就需要抛出。通常使用ApplicationException extends RuntimeException来进行处理 。
VO:View Object,视图对象。当从数据库返回的查询结果不能被某一个实体直接接受的话,我们就需要创建VO来接受。
2.4、安全规则
接口访问权限:通常除了系统内的API接口供给H5使用不需要访问权限,其他接口均有访问权限。通过在拦截器里面拦截用户请求,对用户进行Token和签名校验,通过才能访问该接口,也可以防接口被攻击。
接口跨域考虑:在nginx配置跨域配置。
预防DDOS攻击:
特别说明:但第三方接口的我们系统接口的话,需要设置接口白名单。
2.5、上传文件
阿里云OSS:
2.6、接口访问速度,并发量
索引:通过增加索引来提高数据库的查询速度,进而提高接口的响应速度。
缓存: 使用redis等缓存工具提高响应速度。
@Controller和@RestController的区别?
@Controller:返回的结果可以用modolAndView来接受,响应到具体的页面。
@RestController:在@Controller基础上增加了@requestBody,返回具体的json数据。