你想知道的前后端协作规范都在这里
这是第157篇没有水的原创文章。想要获取更多原创文章，请搜索公众号【正彩云前端团队】关注我们~
一、简介
您还在为如何制定前后端协同规范而发愁吗？干货在这里。本文将带你了解我们团队长期积累和实践的前后端协作规范。看完这篇文章，回去大胆拒绝你不合理的后端设计吧！
2. 为什么我们需要协作规范？
如果你想在团队内部推行一套规范，那么首先你要知道为什么需要制定协作规范？有规范有什么好处？
随着前后端分离开发模式的发展，前后端逐渐向两个方向分道扬镳，各有精耕细作和专业专长。前端更注重交互视觉体验，而后端对高并发、高性能、高扩展性的要求更高。这导致了大部分前端和后端之间的所谓“代沟”。我不知道你的数据是怎么存储的，你也不知道我的页面是怎么渲染的。
因此，有必要制定前后端开发规范，以弥合代沟。有了协同规范，前后端开发有了默契，也提高了开发效率，降低了沟通成本。
3.协作流程规范
首先是协作的流程规范。相信每个团队在前后端协同上都有自己的开发模式和开发流程，保证效率和质量。我们团队前后端协同的大致流程如下图所示：
- 需求导入和交互式可视化导入分析：对于产品导出需求，涉及的各方包括产品、前端、后端、测试和UED。就需求的认知达成一致是开发的第一步。
- 接口设计，前后端对接接口：后端提供接口，前后端在接口领域的设计上要达成一个大方向。
- 技术方案评审：开发前进行技术方案评审，确保各方对需求有统一认识，双方重新确认接口领域的可行性。
- 并行开发，前后端自测：前后端并行开发。在这个阶段，前端可以模拟数据进行页面渲染。
- 开发环境联调：前后端自测完成后，在开发环境上完成接口联调。
4.如何制定接口规范？
- 会前：
- 在后端接口定义 URL 和输入输出参数之前， 前后端需要一致 .
- 文件规格：
- 接口注解需要写清楚：模块、枚举、必填/非必填、输出参数是否可以为null
- 接口需要向后兼容。如果不兼容，则需要评估并通知相应的业务方。
- 如果接口文档有变化，前端需要及时同步
- 后端需要保证文档中定义的参数可以正常请求接口，功能正常稳定
- 计量单位约定：
- 时间：统一使用 13 位时间戳
- 金额：单位分为积分，可根据业务情况选择
- 请求接口 URL & 请求方法
- Post接口不允许使用Get参数传递
- 必须使用post接口
应用程序/json模型 - 接口命名应尽可能符合语义。接口命名不能太相似，难以区分，容易混淆。
- 输入
- 保证同一个应用字段中相同含义的字段名称一致
- 商家 ID/ID 必须是 字符串类型 , JS 有最大数量限制
- 同一页面不同的tab，界面尽量保持一致
- 参
- 接口参数格式要统一
- 接口不应返回“服务器内部异常”、“网络异常”等难以理解的错误信息。离线环境可以返回错误堆栈以方便故障排除。
- 前后端数据列表相关接口，如果返回为空则返回空数组
[]或空集合{}，有利于数据层面更高效的协作，减少前端很多琐碎的空值判断，特殊情况的特殊分析 - 接口输出参数根据页面要求返回有效字段，避免吐出过多无用字段
- 枚举值应尽量返回中英文描述
5.协作中的不良案例
下面总结了我们团队在协作中遇到的典型不良案例和解决方案。相信大家在开发过程中都遇到过类似的痛点：
类型一：前端条件逻辑判断过多
【现象】
-
按钮和组件是否显示，前端需要通过大量字段进行条件逻辑判断；同一页面不同场景下前端调用的接口不同
// 按钮复制，显示逻辑
{(((record.state === 'RESULT_CONFIRM' && isCurrentUserCreate) ||(record.state === 'RESULT_CHECK' && isCurrentUserCreate && currentUserCanCheck )) && <按钮> 确认</ Button >}{['DREFT'，'AUDIT_FAILD'，'REVOKE']。包括(record.state) && isCurrentUserCreate && <按钮> 修改</ Button >}
// A场景调用接口1，B场景调用接口2，C场景调用接口3和4
如果（身份证）{
这个。操作='修改'；
const res = 等待这个。获取信息（ID）；
...
}否则如果（来源）{
const res = 等待这个。 fetchSourceInfo(id:source);
...
} 别的 {
const res = 等待这个。 fetchBasicInfo();
...
}
复制代码
【解决】
- 控制前端显示逻辑判断放在后端处理，前端尽量减少现场判断。
注：如果功能简单，前端也可以做判断 ，如何辨别是否简单？从代码层面来说，比如If判断中的条件多于2个，而按钮显示的条件多于2个，可视为复杂逻辑，将逻辑移至后端处理。建议一开始就把它当成复杂的，这样以后就不需要调整了。
//按钮显示
前后端约定好 按钮的显示返回一个数组，数组具体返回哪些逻辑写在后端。
[
{ name: 'confirm'， type: 'resultConfirm'},
{ name: 'Revise'， type: 'edit' },
]
复制代码
【益处】
- 将逻辑收敛到后端， 当出现问题或改变逻辑时，只需一方排查或修改 .也就是如果能在一端完成，千万不要让两端都干了，可能会出现两者不一致的情况。
类型二：前端二次数据处理过多
【现象】
- 页面同一张表显示的数据是两个接口拼接的
- 接口数据返回格式不符合前端渲染逻辑，需要二次处理
【解决】
1、做好后端数据整合，避免前端数据重组。
2、在树形数据展示的场景下，如果数据不大，后端会返回全量，如果数据量太大，会异步返回数据，但是后续echo和搜索显示在异步返回。
3、同一个业务功能可以一个接口完成，不分接口。后端业务可复用，新接口封
【益处】
- 降低前后端数据处理成本，提升性能和用户体验
类型3：枚举值，下拉框数据由前端维护
【现象】
-
列表页文档状态由前端枚举值维护。如果新的枚举需要在前端和后端进行更改，最终的显示状态可能会不一致。
// 状态值映射
常量 getStatusName = (状态) => {
开关（状态）{
案例0：
返回'草稿'；
情况1：
返回“待批准的部门”；
案例2：
返回“等待财务审查”；
案例3：
return '待审核的单位';
案例4：
返回“审查中”；
...
默认：
休息;
}
}
复制代码
【解决】
-
为保证状态是可扩展的，如果后端做了枚举，前端不需要维护状态值，以后端提供的接口为准。
-
如果状态是固定的，例如选项为[Yes, No]，则不需要从后端返回。
// 从后端界面返回下拉框选项
{
结果： [{
代码：字符串
名称：字符串
}]
}
复制代码
【益处】
- 当枚举值发生变化时，只需要更新后端，也避免了迭代过程中前后端不一致的情况。
类型四：PC端数据结构不适用于App端
【现象】
- App端的布局风格比PC端稍微复杂一些。如果App端盲目使用PC端的接口数据，需要在前端进行特殊处理。比如文档的App端同时放在同一张卡片里，卡片里面的标题、内容、按钮显示也是有区别的。
【解决】
- 判断前端处理工作量，后端需要增加新的接口来实现App的不同功能。
【益处】
- 降低前端处理逻辑成本，提升APP用户体验
类型5：同一个业务域中相同含义的接口字段名称不统一
【现象】
- 关于返回结果：
响应数据,响应结果 - 关于时间：
创建时间,queryEffectStartingBeginTime,惩罚开始时间 - 关于名称：
受罚机构名称,响应者姓名,惩罚对象名称 - 关于身份证：
受惩罚的组织 ID,惩罚对象Id
【解决】
- 前端和后端共同维护一个字段字典，保持同一个业务字段的命名一致，避免不必要的字段转换。
类型6：金额计算结果由前端提交给后端存储
【现象】
- 在前端页面输入支付金额除以总金额，计算支付比例，最后点击保存按钮将数据提交到后台界面；
【解决】
- 金额计算：视存储是否为限，非存储纯展示可在前端计算， 存储的统一由后端计算 .
类型7：前端维护业务配置类型代码
【现象】
- 以多个表单项（下拉框、输入框、单选框等）的值作为条件，判断一个表单项（附件、单选框、输入框等）是否需要、显示或隐。所以前端需要写很多动态验证逻辑，而且每个分区涉及的动态验证逻辑都不一样，有些验证条件还是写死了。
【解决】
- 配置验证规则的页面可以根据分区配置生成识别码，后端可以提供通用的验证接口。前端将值传给后端，然后返回验证结果是否通过。
// 输入参数： { code : '99900' , // 分区码 identity : '11111' , // 识别码 data :[ // data { key : 'catalog' , value : 'A07' , }, { key : 'assetApproval' , value : 0 , } ] } // 返回值：{ result : true } 复制代码
类型8：前端直接调用其他业务线后端的接口
【现象】
- 合同清单 页面，点击新建项目采购合同按钮，弹出框会调用 项目采购 接口在那边。
- 由于合同和采购是不同业务线的后端，接口对接和后期沟通维护的成本会比较高。比如当接口发生变化时，需要跨业务线通知对应的前端（后端不一定知道是哪个前端）；并且接口返回的大量字段的前端没有被使用。
【解决】
- 在后端业务耦合的情况下，需要自己的业务线后端来整合数据；如果只是展示不属于自己业务的数据，后端不会处理
类型9：后端分页接口的数据返回格式不统一
【现象】
- 目前分页接口的数据返回格式并不统一，有以下几种形式：
// 表格一：{ result : { data : [], total : 0 , } } // 表格二： { result : { data : [], pagination : { total : 0 , pageSize : 10 , pageNo : 1 }, } } // 表格三： { result : { data : [], total : 0 , pageSize : 10 , pageNo : 1 } } 复制代码
【解决】
- 建议后台界面统一格式如表三。
类型 10：一个后端接口拆分多个
【现象】
- 在提交之前调用三个不同验证接口的表单页面。三个验证接口的输入参数也不同，前端需要组装各种类型的数据。
【解决】
- 多个验证接口和提交接口合并为一个提交接口。
- 验证失败时，接口返回值区分阻塞和提醒
- Blocking：弹窗提醒，用户只能关闭弹窗
- 提醒：弹出查询，用户点击“继续提交”后，继续调用提交接口，此时添加入参标识跳过此步验证
6.效果
基于一套合理可行的协同规范，前端和后端可以看到从开发到上线的诸多成果：
- 降低沟通成本，减少不必要的扯皮，加快开发进度；
- 缩短联调时间，减少联调阶段的代码调整，保证开发效率；
- 减少测试阶段排查问题的归属，加快测试进度，保证质量；
- 易于故障排除和在线修复。
七、总结
简而言之：如果你发现前端处理的逻辑很多，那就是协作规范有问题！前端更注重交互和渲染的逻辑，应该尽量避免复杂的业务逻辑处理。万事开头难！推一套规范需要时间，前端和后端的同学都要多一些耐心和理解。
推荐阅读
开源作品
- Zhengcaiyun front-end tabloid
开源地址 www.zoo.team/openweekly/ （小报官网首页有微信交流群）
- 产品选择sku插件
职业生涯
ZooTeam是一支年轻、充满激情、富有创造力的前端团队，隶属于正彩云产品研发部，基地位于风景如画的杭州。团队目前有90多名前端合伙人，平均年龄27岁，其中近40%是全栈工程师，妥妥的青年风暴群。成员由来自阿里、网易的“老兵”，以及浙江大学、中国科技大学、航电大学等学校的新生组成。除了日常业务对接，团队还在材料系统、工程平台、搭建平台、性能体验、云应用、数据分析与可视化等领域进行技术探索和实战，推动和实施了一系列内部技术产品。探索前端技术系统的新前沿。
如果你想改变，你已经被东西折腾了，希望开始折腾东西；如果你想改变，你被告知你需要更多的想法，但你不能打破游戏；如果你想改变，你有能力做到那个结果，但你不需要你；如果你想改变你想要完成的事情，你需要一个团队来支持，但没有地方让你带领人；如果要改变既定的节奏，那就是“5年工作时间，3年工作经验”；如果你想改变原来的感悟是好的，但总有那层窗纸的模糊……如果你相信信仰的力量，相信平凡的人可以成就不平凡的事情，相信他们可以遇到一个更好的自己。如果你想参与到业务腾飞的过程中，亲自推动一个业务理解深入、技术体系完善、技术创造价值、外溢影响力的前端团队的成长，我觉得应该讲话。随时，等你写东西，发给[ [电子邮件保护]](/cdn-cgi/l/email-protection)
版权声明：本文为博主原创文章，遵循CC 4.0 BY-SA版权协议。转载请附上原文出处链接和本声明。
这篇文章的链接： https://homecpp.art/2507/7171/0819
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明
