这是第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 版权协议,转载请附上原文出处链接和本声明
本文链接:https://www.qanswer.top/22622/16520711
标签:返回,需要,前端,前后,规范,接口,协作 From: https://www.cnblogs.com/amboke/p/16664706.html