发生了什么

换电业务里,用户在网点电柜前扫码换电池:把没电的电池放进柜子,取走一颗满电的。电柜上贴着二维码,码里带着这台电柜的编号。用户扫码后应该直接落到这台电柜的详情页,页面显示柜里有哪些满电电池、能不能换,用户就地开始换电。

多数用户不先打开小程序,而是直接用支付宝的“扫一扫”扫电柜上的码。这时支付宝会拉起换电小程序,并把码里的参数交给小程序,电柜编号就放在启动参数的 qrcode 字段里。小程序的入口在启动时读出这个参数,再打开对应电柜的详情页。正常进入方式因此只有一步:扫一次码,直接到详情页。

这次要处理的是另一个问题:从支付宝进入小程序时白屏偏多。入口处原本有一段对支付宝客户端的版本下限校验——小程序调用支付宝提供的接口确认客户端版本,版本过低就提示用户升级。评估时看到它要求的最低客户端版本是很久以前发布的,几乎没有用户还用这个版本,判断这段校验实际不会命中,于是把这段与支付宝端的交互整段删除,想减少进入时的等待。

删除上线后,反馈出现了:用户用支付宝扫一扫扫电柜码,进入换电小程序后停在首页,没有自动打开电柜详情页,需要在小程序里再扫一次码。反馈时共 4 例,都发生在小程序需要重新加载的时候,也就是用户此前没打开过、或它的后台进程已经被系统回收;小程序还在后台、被直接切回的那部分用户没有这个问题。

本质

这段版本校验看起来只做一件事:判断客户端版本够不够,不够就提示升级。实际上它同时承担了读取外部参数的职责:从启动参数里取出 qrcode、把这个值交给路由、再打开详情页的代码,就写在这个校验块内部。对“从支付宝扫码进来”这条来路,它是唯一一处读参数的地方。

  1. 支付宝拉起小程序时,电柜编号放在启动方法的启动参数里,键名是 qrcode。
  2. 入口执行启动逻辑,进入版本校验块;校验块内部先把 qrcode 取出来,交给路由打开对应电柜的详情页。用户看到的就是扫码直达。
  3. 这次改动把整个校验块删掉:版本判断没有了,读 qrcode 的那几行也一起没有了。入口启动时没有任何代码再从启动参数里取值,qrcode 只能拿到空值。
  4. 路由拿到空值,按“没有指定电柜”处理,打开首页。用户停在这里,得在小程序里再扫一次码才能进入详情页。
  5. 小程序已经在后台运行时被切回前台,不会重新执行这段启动逻辑,页面手里的状态还在,所以这部分用户没有感知。问题只在需要重新加载的进入方式上暴露。

版本下限判断和外部参数解析写在同一段入口代码里,删掉“不会命中”的判断时,唯一读取扫码参数的那几行也一起没了。

修复方向是把参数解析从版本校验里拆出来,放在启动逻辑最前面:先读启动参数,读到电柜编号就先打开详情页;版本提示改成独立的可选动作,删掉或保留都不影响跳转。入口还应留一条兜底:从外部拉起但没拿到参数时,页面仍提供再次扫码的入口。处置是把这次入口改动回滚,属于把入口恢复原状的止血;回滚是否完成、回滚后是否复测尚未确认,这里不声称已经修好。

下面两段 JavaScript 代码是按上述机制写的脱敏教学示例,只对比参数解析放在什么位置,不代表实际项目源码或已上线实现;事故项目使用的技术栈未确认。

错误代码

// 入口启动逻辑(脱敏教学示例):版本校验整段删除后的写法
App({
  onLaunch(options) {
    // 为什么错:读 qrcode 的代码原本写在版本校验块内部,
    // 校验块被整段删掉后,启动阶段再没有任何地方取这个参数
    const qrcode = '';

    if (qrcode) {
      // 拿不到电柜编号,这里永远不会执行
      this.router.openCabinetDetail(qrcode);
    } else {
      // 结果:用户扫码进来却停在首页,要再扫一次码
      this.router.openHome();
    }
  }
});

修复代码示例

// 同一处入口(脱敏教学示例):解析独立出来,先取参数再决定去哪
App({
  onLaunch(options) {
    // 修复:启动参数由入口直接读取,不再依附版本校验块
    const query = (options && options.query) || {};
    const qrcode = query.qrcode || '';
    this.globalData.pendingQrcode = qrcode;

    if (qrcode) {
      // 扫电柜码进来就直接落到详情页
      this.router.openCabinetDetail(qrcode);
      return;
    }
    this.router.openHome();

    // 版本提示保持独立,删掉它也不会影响上面的参数解析
    this.checkClientVersionIfNeeded();
  }
});

下次遇到这些场景要警惕

  1. 准备删除一段“实际不会命中”的入口判断时:先把这段代码除判断之外还读了哪些启动参数、写了哪些页面状态、调了哪些接口逐条列出来,确认这些职责已有独立出口再删;删完把各种进入方式各走一遍,看是否仍落到目标页。
  2. 涉及外部应用拉起小程序、靠启动参数决定落地页的改动:在“小程序没有在后台运行”的条件下用真实二维码扫一次,看是否直接到详情页;再在“小程序已在运行”的条件下扫一次。两者都要覆盖,因为启动逻辑只在重新加载时执行。
  3. 处理入口白屏、启动慢这类问题而准备删减外部交互时:删减前后都对启动参数做一次记录,扫码进入时把 qrcode 的值打出来对比;参数为空还是不为空,能直接区分“交互变少了”和“参数没读到”。
  4. 入口代码里出现“只在极低版本才命中”的分支时:不要只按命中率评估去留,要按它是否顺带承担别的职责评估,把版本提示、参数解析、路由跳转拆成各自独立的步骤。