你是否在为如何制定前后端协作规范而发愁?干货来啦,一文带你了解我们团队内部沉淀并践行已久的前后端协作规范,读完本文,回去大胆拒绝你后端的不合理设计!
假如你要在团队内部推一套规范,那么首先你得知道为什么需要制定协作规范呢?有规范会带来什么好处呢?
随着前后端分离开发模式大行其道,前端和后端已经在两个方向上渐行渐远,各自深耕细作、术业专攻。前端更加关注交互视觉体验,而后端对高并发、高性能、高扩展上要求更高。这就导致大部分的前端和后端之间会存在所谓的"代沟",我不知道你的数据如何存储,你不知道我的页面如何渲染。
因此,很有必要制定前后端开发上的规范来抹平代沟,有了协作规范,便有了前后端开发默契,也因此达到了提高开发效率、降低沟通成本的作用。
首先是协作的流程规范,相信每个团队在前后端协作中都有各自的开发模式和开发流程来保障效率和质量,我们团队的前后端协作大致流程如下图所示:
接口注释需要写清楚:模块、枚举、必填/非必填、出参是否可能为 null
接口需要向下兼容,如果不兼容需要评估并且通知相应的业务方
接口文档上面有变更需及时同步前端
后端需保证文档上定义的参数,可以正常请求接口且功能正常稳定
Post 接口不允许使用 Get 传参方式
Post 接口必须使用 application/json
模式
接口命名应尽量符合语义,接口命名不要过于相似,难区分,易混淆
[]
或空集合 {}
,有利于数据层面上的协作更加高效,减少前端很多琐碎的 null 值判断,特殊情况特殊分析以下总结了我们团队内部在协作中遇到的比较典型的 Bad Case 以及解决方案,我相信大家在开发过程中也遇到过类似的痛点经历:
【现象】
// 按钮文案、显示逻辑
{((record.state === 'RESULT_CONFIRM' && isCurrentUserCreate) ||(record.state === 'RESULT_CHECK' && isCurrentUserCreate && currentUserCanCheck )) && <Button>确认</Button>}
{['DREFT', 'AUDIT_FAILD', 'REVOKE'].includes(record.state) && isCurrentUserCreate && <Button>修改</Button>}
// A 场景调用接口 1,B 场景调用接口 2,C 场景调用接口 3 和 4
if (id) {
this.operation = '修改';
const res = await this.fetchInfo(id);
...
} else if (source) {
const res = await this.fetchSourceInfo(id: source);
...
} else {
const res = await this.fetchBasicInfo();
...
}
【解决】
注:如果功能简单,前端也可以做判断,如何鉴定是否简单?从代码层面比如 If 判断中超过 2 个条件,按钮显示超过 2 个条件,可视作复杂逻辑,逻辑移到后端处理。建议一开始就视作复杂去处理,这样后期就不用再调整。
// 按钮展示
前后端约定好 按钮的显示返回一个数组,数组具体返回哪些逻辑写在后端。
[
{ name:'确认',type:'resultConfirm'},
{ name:'修改',type:'edit' },
]
【好处】
【现象】
【解决】
1、后端做好数据的整合,避免数据在前端的重组。
2、Tree 数据展示的场景,如果数据不大后端全量返回,如果数据量过大异步返回,但异步返回存在后续的回显和搜索展示方面问题。
3、同一个业务功能,一个接口搞定,不要分接口进行,后端业务考虑复用可包装新接口或原接口加参数兼容。
【好处】
【现象】
// 状态值映射
const getStatusName = (status) => {
switch(status) {
case 0:
return '草稿';
case 1:
return '待部门审批';
case 2:
return '待财务审核';
case 3:
return '待单位审核';
case 4:
return '审核中';
...
default:
break;
}
}
【解决】
确保状态可扩展,后端已经做了枚举的情况下,前端不需维护状态值,以后端提供接口为准。
如果是状态定死的情况下譬如:选项为【是、否】可无需后端返回。
// 由后端接口返回下拉框选项
{
result: [{
code: string
name: string
}]
}
【好处】
【现象】
【解决】
【好处】
【现象】
response.data
、 response.result
createAt
、queryEffectStartingBeginTime
、penaltyBeginTime
punishedInstitutionName
、responderName
、penaltyObjectName
punishedOrganizationId
,penaltyObjectId
【解决】
【现象】
【解决】
【现象】
【解决】
配置校验规则的页面可根据区划配置后生成标识码,然后后端可提供一个通用的校验接口,前端把值传给后端,然后返回校验结果是否通过。
// 入参:
{
code: '99900', // 区划代码
identity: '11111', // 标识码
datas:[ // 数据
{
key: 'catalog',
value: 'A07',
},
{
key: 'assetApproval',
value: 0,
}
]
}
// 返回值:
{
result: true
}
【现象】
业务线 A 列表页面,点击新建按钮,弹框调用业务线 B那边的接口。
由于 A 和 B 是不同业务线后端,接口对接以及后期的沟通维护成本会比较高。例如该接口发生改动,需要跨业务线通知到对应的前端(该后端还不一定知道前端是哪位);并且接口返回的大量字段前端都用不到。
【解决】
【现象】
目前分页接口的数据返回格式不统一,已有如下几种形式:
// 形式一:
{
result: {
data: [],
total: 0,
}
}
// 形式二:
{
result: {
data: [],
pagination: {
total: 0,
pageSize: 10,
pageNo: 1
},
}
}
// 形式三:
{
result: {
data: [],
total: 0,
pageSize: 10,
pageNo: 1
}
}
【解决】
【现象】
【解决】
阻塞式:弹框告警,用户只能关闭弹框
提醒式:弹框询问,在用户点击"继续提交"后,继续调用提交接口,此时增加入参标识跳过此步校验
基于一套合理可行的协作规范,前后端从开发到上线的各个阶段都能够看到诸多成效:
一言以蔽之:如果你发现前端在处理大量的逻辑,那么就是协作规范存在问题啦!前端更多的是关注交互、渲染上的逻辑,应尽量避免复杂的业务逻辑处理。万事开头难!推一套规范是需要时间去沉淀的,前端和后端同学都应多些耐心,多些理解。
如果你觉得这篇内容对你挺有启发,我想邀请你帮我两件小事
1.点个「在看」,让更多人也能看到这篇内容(点了「在看」,bug -1 😊)
政采云前端团队(ZooTeam),一个年轻富有激情和创造力的前端团队,隶属于政采云产品研发部,Base 在风景如画的杭州。团队现有 90 余个前端小伙伴,平均年龄 27 岁,近 3 成是全栈工程师,妥妥的青年风暴团。成员构成既有来自于阿里、网易的“老”兵,也有浙大、中科大、杭电等校的应届新人。团队在日常的业务对接之外,还在物料体系、工程平台、搭建平台、性能体验、云端应用、数据分析及可视化等方向进行技术探索和实战,推动并落地了一系列的内部技术产品,持续探索前端技术体系的新边界。
如果你想改变一直被事折腾,希望开始能折腾事;如果你想改变一直被告诫需要多些想法,却无从破局;如果你想改变你有能力去做成那个结果,却不需要你;如果你想改变你想做成的事需要一个团队去支撑,但没你带人的位置;如果你想改变既定的节奏,将会是“5 年工作时间 3 年工作经验”;如果你想改变本来悟性不错,但总是有那一层窗户纸的模糊… 如果你相信相信的力量,相信平凡人能成就非凡事,相信能遇到更好的自己。如果你希望参与到随着业务腾飞的过程,亲手推动一个有着深入的业务理解、完善的技术体系、技术创造价值、影响力外溢的前端团队的成长历程,我觉得我们该聊聊。任何时间,等着你写点什么,发给 ZooTeam@cai-inc.com