发生了什么
平台上的商户分两级:一级仓负责拓展,二级仓挂在一级仓名下,各自给用户提供换电服务。商户可以给用户开通“免套餐”,用户在约定期限内换电不单独付费。每一次开通都用一张卡代表这份资格,卡有两种来源:一种是二级仓自己采购的,另一种是一级仓从自己的额度里分配给二级仓的。一级仓分配下来的卡初始是待分配状态,二级商户把它绑定到某个用户名下,绑定关系记在卡上;用户不用了可以解绑,卡回到待分配,二级商户还能把同一张卡换绑给另一个用户。
正常流程里,绑定和换绑之前都要先做一次校验,确认这张卡的来源和品类允许这次操作,校验通过才写入绑定关系。所以只要校验结论是“不允许”,用户就绑不上,页面只提示一句来源或品类不对。
9 月 17 日晚上,“租电套餐支持转让”的需求上线,改动了免套餐分配链路的查询和分配前校验。新校验要判断一张卡的来源是否合法,依据是这张卡最初由哪一张分配单产生,用这个编号再去找实际的卡。9 月 18 日上午 9 点 24 分起,二级商户给用户绑定由一级仓分配下来的换电免套餐卡,操作被拦住,页面报“兑换券来源或品类错误”,两位仓经理都复现,卡停在待分配,用户绑不上。确认影响 2 名用户、23 笔订单,业务投诉 1 起;拦截发生在校验环节,没有产生脏数据,也没有资金损失。
本质
问题出在新校验要读的那个编号,查卡的那条 SQL 从来没查过它。
- 绑定和换绑共用一个查卡方法,按卡的编号取卡信息。这条 SQL 的字段投影一直只查卡号、来源类型、品类、状态、当前绑定用户这几列,从未查过分配单编号。
- 同一个数据访问接口里还有六条同类查询,它们都带上了分配单编号,只有换绑用的这一条没有。这条 SQL 不是这次改坏的,是它一直被当成“够用”的查询沿用下来。
- 新校验在来源类型是“一级分配”时,取分配单编号去找卡;如果卡是二级仓自采的,走的是卡号分支。同一段校验,自采卡能通过,分配卡通不过。
- 卡对象里这一列没有对应的查询结果,字段就是 null。校验只看取出来的编号是不是空,空就返回“兑换券来源或品类错误”,换绑中断。
- 新校验挂在换电和租电共用的校验方法上,本次需求是租电改造,校验却没有纳入这个需求的灰度开关。于是改动范围是租电,先被拦住的是换电这条老链路。
关键在第 4 步:空在这里有两种含义,一种是这张卡的来源真的不合法,另一种是字段压根没查出来。校验把两种空合并成同一句“来源或品类错误”,合法数据被判成非法,排查时也只能看到一句业务提示,看不出是查询没取到值。
处理分两层。止血是把这次需求的代码回滚,9 月 18 日 11 点 45 分左右完成,被拦的操作恢复。修复方向是给换绑用的查询补上分配单编号,并让校验在分配卡取不到编号时单独报“查询字段缺失”,不要伪装成业务非法;修复是否完成、免套餐链路是否验证过、是否重新发布,现有信息没有说明,修复上线状态待确认。
错误代码
public interface CardMapper {
// 换绑前按卡编号取卡信息,绑定与换绑共用
// 为什么错:投影里没有 allocation_no,同接口其余同类查询都带了这一列
@Select("select id, card_no, source_type, card_type, state, new_user_id "
+ "from package_card where id = #{cardId}")
CardDetail queryForRebind(@Param("cardId") long cardId);
}
public void checkBindFreePackage(long cardId, int sourceType) {
CardDetail detail = cardMapper.queryForRebind(cardId);
// 为什么错:分配卡依赖 allocationNo,但上面的查询没取,取到的恒为 null
String cardGuid = sourceType == SOURCE_ALLOCATED
? detail.getAllocationNo()
: detail.getCardNo();
// 为什么错:null 被当成“来源不合法”,把查询缺陷说成业务拒绝
if (cardGuid == null || !cardService.exists(cardGuid)) {
throw new BizException("兑换券来源或品类错误");
}
bind(cardId, detail.getCardType());
}
修复代码示例
public interface CardMapper {
// 补上 allocation_no:公共查询的投影要覆盖所有调用方引用的字段
@Select("select id, card_no, source_type, card_type, state, new_user_id, allocation_no "
+ "from package_card where id = #{cardId}")
CardDetail queryForRebind(@Param("cardId") long cardId);
}
public void checkBindFreePackage(long cardId, int sourceType) {
CardDetail detail = cardMapper.queryForRebind(cardId);
if (sourceType == SOURCE_ALLOCATED) {
String allocationNo = detail.getAllocationNo();
// 字段缺失是查询缺陷,按技术异常抛出并带上卡编号,便于直接定位
if (allocationNo == null) {
throw new IllegalStateException("分配单编号未查询到, cardId=" + cardId);
}
// 只有真的查到了编号,才判断来源是否合规
if (!cardService.exists(allocationNo)) {
throw new BizException("兑换券来源或品类错误");
}
}
bind(cardId, detail.getCardType());
}
下次遇到这些场景要警惕
- 给一条被多处复用的查询新增校验字段:先把新代码引用的字段和这条 SQL 的投影逐列对一遍,再拿一条来源类型为“一级分配”的数据跑一次绑定,在日志里确认该字段有值,而不是只验证自采数据。
- 校验同时服务两条业务线:把校验的每个入口和每条来源分支列出来,各自造一条数据走一遍。本次只验证了改造范围内的租电,换电这条老链路先被拦,说明“改哪条就只测哪条”不够。
- 校验准备返回“非法”之前:把“字段没取到”和“业务上不允许”拆成两个结果并分别告警,观察错误提示的分布;如果只剩一句业务提示,线上只能看到用户操作失败,定位不到查询本身。
- 改动挂在公共路径上:确认这个入口的所有调用方是否都在本次灰度或开关的覆盖范围内,不在范围内的调用方要单独回归,别把需求范围当成影响范围。