发生了什么
换电业务在城市里铺开,靠的是一批“网点”:门店、停车场或场站里放换电柜,用户把没电的电池放进去,换一块满电的带走。网点正式上线前要先签约,系统里会先记下点位、房东和结算信息。房东是把场地交出来做合作经营的一方;结算时钱付给谁、发票开给哪个主体,记在这位房东名下的“商户”档案上,每份商户档案有一个商户编号。签约时还要登记银行卡:租金和电费两类费用各对应一张卡,登记的就是这两类费用的收款卡。
正常流程是这样的:运营或业务人员在签约页选中一位房东,页面按这位房东的档案去取已经绑定的银行卡列表,选中一张提交,签约单继续往下走到合同环节。老的线下签约页一直按房东档案取卡,请求里只要房东标识,不需要商户编号,后端也不校验这个字段。
7 月的一次网点签约优化需求,要解决“一个手机号可能对应多个房东”的问题:同一个手机号下面挂着好几位房东,各自的商户档案和结算信息不同,只按手机号取资料会取错人。为此这次改动新增了一个取银行卡信息的接口,它要求带上商户编号——先定位到具体那一位房东名下的商户,再返回卡列表;原来那个取卡接口不做这项校验。
前端开发在改这段历史逻辑时,分支判断写错了,把老的线下签约页也接到了新接口上。老页面手上没有商户编号,请求带过去的这个参数是空的,新接口在校验这一步就拒绝了,页面弹出“商户编号不能为空”。卡列表没有返回,运营填不了银行卡,签约流程停在这一步,网点线下签约做不下去。
本质
错误不在“要不要商户编号”这条规则,而在于一次需求改造把两个流程的取卡入口接混了。
- 原流程:老的线下签约页按房东档案取卡,请求只带房东标识,后端不校验商户编号,这条路一直可用。
- 本次需求新增的取卡接口:面向“一个手机号对应多个房东”的场景,必须先用商户编号把房东定位到唯一一位,再返回这位房东名下的卡列表。
- 前端改动历史逻辑时,判断走新接口还是老接口的条件写错了。判断本应看“当前是哪个签约流程”,实际写的条件让老的线下签约页也命中了新分支。
- 老页面只有房东标识,没有商户编号,请求就带着空的商户编号发到了新接口。
- 新接口入口校验要求商户编号非空,参数为空直接返回校验失败,页面把失败原因原样弹成提示,卡列表为空。
两个接口的入参要求不同,前端在一个入口里混用了新接口,老流程于是发出一条注定被拒的请求。
修复是把老的线下签约流程改回调用老的取卡接口,新接口只留给需要按商户定位房东的新流程;本次需求涉及的其他灰度接口调用点也同步核对了一遍。修复上线状态待确认。之所以要连带核对其他调用点,是因为这类“新增必填参数”的接口一旦被老页面复用,表现都一样:页面不报代码错误,只是在业务走到某一步时被校验挡住,不逐条流程走一遍很难发现。
错误代码
// 签约页取银行卡列表:老线下签约和新流程共用一个入口(接口路径为示意)
function loadBankCards(ctx) {
// 为什么错:拿“有没有手机号”当新流程的判据。
// 老的线下签约页同样带手机号,于是也被判成新流程,走进了新接口分支
if (ctx.phone) {
return request('/card/list/v2', {
phone: ctx.phone,
// 为什么错:商户编号只在新流程上下文里才有,老页面这里是 undefined,
// 请求照发不误,服务端校验商户编号非空后直接拒绝
merchantId: ctx.merchantId
});
}
return request('/card/list', { landlordId: ctx.landlordId });
}
// 页面拿到失败结果后,把服务端返回的原因直接弹出来
const res = await loadBankCards(ctx);
if (!res.success) toast(res.message); // 运营看到的是“商户编号不能为空”
修复代码示例
// 按签约流程本身决定走哪个接口,不再靠字段是否存在去猜(接口路径为示意)
function loadBankCards(ctx) {
if (ctx.signFlow === 'ONLINE_MULTI_LANDLORD') {
// 新流程:一个手机号可能对应多个房东,必须先有商户编号才能定位到人
if (!ctx.merchantId) {
// 缺参数在发请求前就报可定位的错,而不是让服务端返回一句笼统的校验失败
throw new BizError('缺少商户信息,请先选择房东档案');
}
return request('/card/list/v2', { phone: ctx.phone, merchantId: ctx.merchantId });
}
// 老线下签约流程:继续用按房东档案取卡的老接口,它不需要商户编号
return request('/card/list', { landlordId: ctx.landlordId });
}
两个分支各自守住自己的入参要求:新流程先确认商户编号存在再发请求,老流程根本不去碰新接口。代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。
下次遇到这些场景要警惕
- 给共用页面或组件加新接口:先列出这个入口被哪些流程复用、每个流程的上下文里有哪些标识,再逐个流程完整走一遍,观察每个流程发出的请求是否带齐了新接口的必填参数。
- 用“某字段有没有值”判断走哪个分支:改成用明确的流程标识、页面来源或业务类型来判断。字段存在只是现象,两个流程很可能恰好都带同一个字段。
- 接口新增必填参数:在契约里标明必填,缺参时返回能定位到调用方的错误;同时全量搜索这个接口的调用点,不要只看本次改动的那一处。
- 灰度需求验收:新功能只在灰度环境可见时,没开灰度的老入口同样要回归一遍——本例正是老入口被新接口拦住,而灰度测试里只盯着新流程就容易漏掉。