前后端交互约定_规范
前后端交互约定、规范
一、结合目前公司情况的痛点总结
- 部分开发人员思想：只要前端开发能做的，那就交给前端做；前端做，服务器没性能问题
- 接口输出和原型不符合，前端需要调用多个接口，进行数据重组转换实现单一功能
- 前端在数据对接和处理上耗费太多精力，应该重心偏移，更注重UI和交互体验
二、职责分离
| 后端 | 前端 |
|---|---|
| 提供数据 | 接受数据，返回数据 |
| 处理业务逻辑，关注服务层，程序的可靠性、稳定性、接口性能、安全性以及数据完整性、一致性等 | 处理渲染逻辑，关注视图层，用户体验效果、页面性能（因为客户看到的是最终页面，页面效果以及数据呈现效果的好坏是最能反映客户的满意度的。客户不关注你用了什么牛逼的技术） |
| 代码跑在服务器上 | 代码跑在浏览器上 |
三、设计规范原则
- 前端应只关注渲染逻辑，而不应该关注数据的处理逻辑。接口返回的数据应该是能够直接展示在界面上的。
- 一个功能应避免多个接口嵌套调用获取数据，后台应该处理好一次性返回。
- 响应格式应该是JSON，而且应避免多级JSON的出现；
- 后端如果需要界面实时刷新数据，不应该要求前端定时器轮询，而要提供类似webSocket之类的功能。
根据这个原则，后端返回的数据应该是所见即所得的数据，而不应该是一层包一层的复杂的JSON，需要前端额外来处理很复杂的去重，排序、深浅拷贝，变形等处理。前端在渲染每一个div，每一个table的cell时，不用担心数据结构会不会不一致的问题。
四、要达到的目的
- 尽可能的缩小沟通成本，开最少的会，确定大部分的事情
- 花最少的时间来写文档，形成统一规范，哪怕不看文档，也知道各种接口的大致逻辑
- 不写重复代码
- 尽可能写高可读性的代码
五、规范等级标识
A：对前端很重要；严格遵守
B：对前端很重要，可能有特殊情况；原则上严格遵守，万一特殊情况需要和前端开发讨论
C：对前端一般重要；尽量遵守，不遵守不需要和前端讨论，引发后果后端开发自己解决
D：建议
E：现阶段不考虑，后续有条件再说
六、一般规范
1、协作流程规范
1.1 需求分析。确保大家对需求有一致的认知；（A）
1.2 设计接口文档。需要相关开发人员进行接口评审，前端需要确认是否符合要求；（A）
1.3 并行开发。前端需要根据接口文档进行Mock, 模拟对接后端接口；（E）
1.4 真实环境联调。联调之前，要求后端做好接口测试；前端将接口请求代理到后端服务，进行真实环境联调；（A）
2、接口文档规范
2.1 接口需要产出接口文档；（A）
2.2 文档要有接口名称、请求方式、请求参数和响应参数，对应的字段说明，类型说明，是否必填；（A）
2.3 接口文档需要相关开发人员一起评审；（A）
2.4对接完成的接口如要变更数据结构，增删参数值，需要和前端讨论，前端需要知道变更影响范围和难易程度，和调整地方；（A）
3、URL语义化规范
例：
协议+域名/IP+端口号+/api+/项目名+/模块名+/一级资源+/n级资源+/动作
关于版本号，可以在模块后增加
/v1/等标识。
4、接口请求协议类型规范
4.1 请求方式，只能用GET和POST；（A）
4.2 不使用resulful接口规范；（A）
4.3 GET只允许传0-2个基础数据类型的参数，重点：【GET方法不可在Body中放置参数】；（A）
4.4 POST Body只能是JSON格式（Content-Type=application/json），只有文件上传用formDate上传（Content-Type=application/x-www-form-urlencoded），文件名统一用file；（A）
4.5 Header只传全局参数，不传业务参数；（A）
4.6 避免频繁修改Header参数；（A）
4.7 不使用cookie；（A）
5、响应结果规范
5.1 所有返回数据需是合法JSON，尽量返回object或者array (二进制文件下载除外)；（A）
5.2 如果数据中包含类型为array的属性，当数据为空时，尽量返回空数组[]，避免返回null，需保持数据格式不变；（A）
5.3如果数据中包含类型为object的属性，当数据为空时，尽量返回空数组{}，避免返回null，需保持数据格式不变；（A）
5.4 返回值中应尽量避免包含无用信息，或者额外的数据结构，仅包含必要数据即可。必要数据指前端需要渲染的数据；（B）
5.5 只要有数据返回，接口请求成功，响应的http状态码必须是200；对应的业务状态码为code，在响应数据中定义；（A）
5.6 数据扁平化，JSON嵌套尽量不要超过三层，超过后应该采取其他实现方式；（C）
1 | { |
6、分页查询规范
6.1 100条以下的数据可考虑前端分页；（A）
6.2 前端需要传：当前页pageNum，每页条数pageSize；（A）
6.3 后端返回：当前页pageNum，每页条数pageSize，总条数total，当页数据items；（A）
1 | { |
7、状态码规范
客户端的每一次请求，服务器都必须给出回应。回应必须包括 code码；
7.1 固定状态码约定（A）
1 | # 10000: 成功 |
7.2 其他状态码分类，首字母为提示等级（D）
1 | 前端后面需要可争对不同等级做不同处理，如：直接message提示；右上角悬浮notification提示；需要手动点确定的confirm提示 |
8、前端请求参数规范
8.1 查询类接口，如果没选的条件，或者查询全部，则此字段不传给后台；（A）
8.2 提交类接口，前端字段不能删，如果没选，或者没填，前端传null 或者 “” ，数组对象同理，保持交互的数据格式不变；（A）
9、时间日期类参数规范
9.1 时间日期格式为 yyyy-MM-dd hh:mm:ss 不允许有24:00:00；（A）
9.2 只有年月日的时间范围：前端传 yyyy-MM-dd 00:00:00 yyyy-MM-dd 23:59:59；（A）
9.3 只有年月日的单个日期：前端传 yyyy-MM-dd 00:00:00；（A）
七、其他约定
7.1、数据状态变更，要单独写接口，不能复用编辑接口；（C）
前端开发不强校验当前单据的状态，和流转后的状态，只提交动作，尽量分成多个接口，不要把提交，审核，删除等接口合并
7.2、列表查询和导出 参数、请求方式保持一致；（A）
如果是整表导出，则导出只是少分页参数
7.3、表示同一意思的字段名，在一个系统中，如不可避免则在同一个功能模块中，不能起多个名字；（A）
反例：如spuId、productId；img、productImg、imgUrl描述的是同一个意思
7.4、接口设计需要结合原型，避免跳转页面需要前端通过URL带大量数据的情况，前端URL跳转不能携带超过三个参数；（B）
7.5、后台参数要和原型对应，不能一个参数对应页面多个参数，或者是多个参数对应一个；（B）
例：手机号，在原型上其实分成了区号，和手机号，那后台要对应两个字段，不应拼接在一起用一个字段表示。例2：前端展示价格，后台不能返回ABC多个价格，让前端根据条件判断显示哪个
7.6、后台返回的单据状态、类型要和原型上状态、类型一对一对应，前端不应该用其他附加字段判断状态；（A）
例：原型上有1、2、3个状态，后台数据库只设计1、2状态，不应让前端通过其他字段判断3状态，应该返回前端的数据就是1、2、3状态。反例：商城优惠券类型，前端需要根据具体的金额是否有值，反过去判断券类型
7.7、核心数据、敏感数据，前端应该不进行运算；后端也不应该接收前端传递的参数；（A）
例：界面上的库存、价格；结算所需要的价格等；前端运算尽量只能是优化体验
7.8、新增和编辑接口，尽可能写成一个，应该保持一样的数据结构，和字段名；（B）
7.9、查询详情的接口，应该和新增/编辑接口保持一样的数据结构，和字段名；（B）
7.10、接口的附带前置条件需要后台自己校验；（A）
例：下单接口：结算前，当前商品是否在收货的国家禁售，不应该是前端先调用【判断是否禁售】，再调用【下单接口】，是否禁售等逻辑应该直接做在下单接口上