前后端接口对接规范文档_和前端对接时 如何提供接口文档

前后端交互接口遵循统一RESTFUL接口原则，构建优良的 REST API,默认使用POST方式发送请求，文件下载采用GET方式请求

目的：

降低沟通成本，减少不必要的扯皮，加快开发进度；

缩短联调时间，减少联调阶段的代码调整，保证开发效率；

减少测试阶段排查问题的归属，加快测试进度，保证质量；

易于故障排除和在线修复。

1.界面URL参数
前端在url上传参只允许传id参数，例如bzid可以传入，标准名称、标准状态等不能通过url传入

通过id调用后台详情接口，来获取界面展示数据，而不是通过url参数中获取

强制不允许url中传入中文参数及有关状态判断参数

如参数值有特殊符合，需要加密，encodeURIComponent加密，接受参数解密decodeURIComponent

2.接口传参注意事项
传给后台数组需要转成json字符串 JSON.stringify

上传文件接口、下载接口、还有请求接口数据都需要对参数进行处理，一般处理参数的函数中，包括增加token、验签、增加公共参数，需要注意上传跟下载接口比较特殊调用时，必需要调用处理参数的函数方法。

批量删除需要给后台id时，以逗号分隔

密码等敏感信息要加密处理

3.接口文档规范
开发前后台要提供接口文档 apipost apifoxs

接口文档中注明接口名称、请求参数、返回结构

接口不合理，要及时沟通

状态值的返回不合理，需要返回状态id跟状态中文名称 zt:1,zt_name:‘已完成’

枚举值应尽量在字段备注中描述清楚，zt=1、2、3分别代表什么含义

4.前端按钮展示、禁用状态判断原则
控制前端显示逻辑判断放在后端处理，前端尽量减少现场判断

按钮是否展示或禁用通过两个及以上状态判断的，需要后台返回一个新的状态值，只能通过一个状态判断

按钮通过状态判断是否展示的，要写好注释，标注好不同的状态是展示按钮还是禁用按钮

5.后台返回错误信息原则
不要精准提示错误信息，密码输入不对，应提示账号不存在或密码错误

后端处理所有的异常(数据库错误、服务器错误等)信息，避免把异常抛到前台 ，防止他人读取到有用信息

6.接口规范
接口返回数据即显示：前端仅做渲染逻辑处理；

关于Boolean类型，JSON数据传输中一律使用1/0来标示，1为是/True，0为否/False；
前后端数据列表相关接口，如果返回为空则返回空数组[] 或空集合{} ，有利于数据层面更高效的协作，减少前端很多琐碎的空值判断，特殊情况的特殊分析
举例：有值时候返回list，值为空时候返回{}或者""

渲染逻辑禁止跨多个接口调用；

前端关注交互、渲染逻辑，尽量避免业务逻辑处理的出现；
参考第四条

请求响应传输数据格式：JSON，JSON数据尽量简单轻量，避免多级JSON的出现；

总结：
如果你发现前端处理的逻辑很多，那就是协作规范有问题！前端更注重交互和渲染的逻辑，应该尽量避免复杂的业务逻辑处理。万事开头难！推一套规范需要时间，前端和后端的同事都要多一些耐心和理解。
————————————————
版权声明：本文为CSDN博主「耶稣与梦」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/Qin_HongKun/article/details/129193916