发生了什么

平台给商户一类“免时长”商品:商户在商城里挑好商品,对应的服务在约定期限内不收费。商品配置按区县粒度做,某个区县没有单独配置时,就展示一份全国通用的商品。商户从商户端首页的商城入口进入,商城按商户所在城市的区县编码决定能看到哪些商品。

正常流程是:商户在首页选中城市,点击商城入口,页面先把这个城市换算成对应的区县编码,再带着区县编码跳到商城,商城按区县编码查出该区县可用的商品。

这次的需求,是让此前不生效的县域商品配置真正生效。后端为此新增了一个换算接口:请求里带首页的城市编码,响应里返回该城市对应的区县编码,两个字段都叫 cityCode。

功能在测试环境测过、产品也验收通过,进入待发布。此时开发在代码评审中认为,每次点击跳转都要重复请求灰度开关和这次的城市换算,而返回值每次都一样,把请求提前到进入页面时更合适。改动落地后,跳转链接拼进去的城市编码来自页面手里的入参(首页城市),接口返回的区县编码没有被用上。

发布次日上午,有城市的商户反馈:进入商城看不到任何商品。同一版本在测试环境里,本次需求涉及的县域也没有显示自己配置的商品,显示的是全国商品。

本质

这个接口有两个同名字段,含义并不相同:

  1. 请求里的 cityCode 是商户在首页选中的城市,页面自己就持有这份值。
  2. 响应里的 cityCode 是接口换算出来的区县编码,商城取商品只认这一个是区县粒度的值。

页面把请求提前之后,本意只是挪动发请求的时机,实际却把拼参数用的值换成了手里现成的那个。跳转链接带出去的是城市编码,商城按区县编码去匹配商品配置,一条都对不上,列表就是空的;全国商品不按区县区分,所以在另一批城市上表现为“看到的是全国商品”。

同一个接口的入参和出参用了同名字段,调用方取了错的那个,城市对不上,商品自然就空了。

比取错字段更值得注意的,是这次改动发生的时点:代码在功能测试和产品验收都通过之后才改,没有走变更评审,回归范围是线下口述的“三个入口能不能正常跳”,顺带提了一句可能影响小程序页面。测试按这个范围回归,跳转确实正常,但“某个区县能看到自己的商品”这条业务结果没有验证——它恰恰是这次需求的目标场景。

修复方向是跳转时统一取响应里的区县编码,不再使用入参的值。该修复已上线,上线后的完整验证情况待确认。

错误代码

下面的示例只保留“取数”和“拼跳转参数”两步,用前端脚本表示。

// 改动后:进入页面时请求一次,结果留给点击时使用
let mallContext = null;
loadMallContext();

async function loadMallContext() {
    // 入参是首页的城市编码,响应里的 cityCode 是换算后的区县编码
    mallContext = await fetchMallContext(homeCityCode);
}

function onEnterMall() {
    if (!mallContext) return;
    // 为什么错:拼跳转参数用的是页面手里的入参城市编码,
    // 商城按区县编码取商品,两个粒度对不上,列表会是空的
    location.href = "/mall?cityCode=" + homeCityCode + "&gray=" + mallContext.grayOn;
}

修复代码示例

let mallContext = null;
loadMallContext();

async function loadMallContext() {
    mallContext = await fetchMallContext(homeCityCode);
}

function onEnterMall() {
    if (!mallContext) return;
    // 跳转只认响应里的区县编码,和商城取商品用的是同一个值
    location.href = "/mall?cityCode=" + mallContext.cityCode + "&gray=" + mallContext.grayOn;
}

下次遇到这些场景要警惕

  • 接口的请求和响应都有同名字段:先对着接口定义确认这两个值的粒度和来源是否相同,让调用方明确只取一个;必要时在响应里换一个不会混淆的字段名,再改调用代码。
  • 在待发布阶段还想动代码:先列出改动会影响的功能结果,按业务结果验证,而不是只验“入口能不能跳”,并确认是否需要变更评审。
  • 回归范围只有口述:要求把场景和预期结果写成清单,其中必须包含本次需求原本要达成的效果——这里是按区县配置的商品要能显示出来。
  • 同一套跳转逻辑被多个入口共用:把每个入口和小程序页面逐个走一遍,并各选一个已单独配置商品的区县,确认看到的是本区县商品而不是全国商品。