发生了什么

用户下单之后要先交一笔押金,交成功这笔订单才继续往下走。

2024 年 11 月,平台做了一次交易链路升级:下单改成新的规则,交押金也换成新的接口。升级之后,在同一个端里完成“下单 + 交押金”是通的——用户在小程序里下单就在小程序里交,在 App 里下单就在 App 里交,页面和接口配套就能走完。

出问题的是跨端操作:用户在一个端下单,再换另一个端交押金。比如在微信或支付宝小程序里下单,也可能是客服代客下单,然后回到 App 里给这笔订单交押金。

App 里的页面不是每次打开都从服务端取最新版,而是打成“离线包”预置在客户端本地——相当于把前端页面随客户端一起装进去,发版之后再由客户端在后台下载更新。用户设备上的包没更新到新版,打开的就还是老页面。

新链路给交押金的请求加了一个表示购买类型的必传参数。老页面的表单里没有这个字段,也没有取这个值的地方,它属于升级之后才出现的要求。这条“新订单 + 老页面”的组合走到提交时就缺参数,押金交不上,订单停在下单之后、未支付的状态。

受影响的下单量和失败提示的具体文案没有确认;能确认的是这类跨端用户交押金不成功,订单停在未支付,有流失风险。

本质

一句话:这次升级同时改了下单和交押金,但两端的页面版本不由同一个开关控制,切换方案却默认用户只在一端操作。

  1. 升级前,下单和交押金是同一套老链路,页面和接口一起老,任何组合都能对上。
  2. 升级后,下单走新链路,交押金换成新接口,新接口要求请求里必须带购买类型。这条要求是按“新页面配新接口”这一种组合设计的。
  3. 出错的一步在切换方案:它只考虑了同一端的新配新、老配老,没有把“一端下单、另一端交押金”列进来。而 App 的页面版本由离线包决定,用户设备上可能是老的;小程序和 App 又各自发版,两边的版本不会同时到位。
  4. 于是新订单进入老页面的交押金表单时,请求里缺这个必传参数;新接口按缺参处理,直接拒绝,这条链路到这里就断了。
  5. 这跟“页面写错了”不是一回事:老页面按自己的逻辑是对的,它只是不知道新链路多了一个参数。缺的是两端版本配对时的兼容处理——新接口没有为“页面还没升级”留出兜底。

一次发布只能保证“同一端新配新”,跨端路径上的版本由两个端各自决定:任何一端的页面没更新,这个组合当场就不成立。

给出的临时处理是:失败时用 Toast 把用户引导到另一个小程序端缴纳押金,或者提示返回首页重新进入。前者换了一个端,后者赌客户端会重新下载离线包,用户容易理解成“再点一次就好”,两种都只是止血,不是修复。

修复方向有两个层面,可以一起做:接口侧不再把购买类型当成页面必传,能从订单记录取到就从订单取,确实取不到时返回明确的引导而不是一条参数错误;发布侧把跨端组合列进验证清单,或者按请求里的页面版本识别老页面,给出更新提示并引导到可用的端。这两层是否已经实施、上线状态待确认。下面代码演示接口侧的兼容处理。

错误代码

// 交押金接口(脱敏教学示例)
@PostMapping("/deposit/pay")
public PayResult pay(@RequestBody DepositPayRequest req) {
    // 为什么错:新链路把购买类型设成页面必传,缺了就把整笔请求拒掉,
    // 而停留在老版本页面的表单里根本没有这个字段
    if (StringUtils.isBlank(req.getBuyType())) {
        throw new BizException("PARAM_MISSING", "购买类型不能为空");
    }
    Order order = orderService.getByNo(req.getOrderNo());
    // 为什么错:订单在下单时已经记下了来源,这里又向页面要一遍,
    // 等于把“页面必须已经升级”写进了接口契约
    return payChannel.pay(order, req.getBuyType(), req.getAmount());
}

修复代码示例

// 修复:页面没传就按订单补齐,补不齐再给可执行的引导(脱敏教学示例)
@PostMapping("/deposit/pay")
public PayResult pay(@RequestBody DepositPayRequest req) {
    Order order = orderService.getByNo(req.getOrderNo());
    if (order == null) {
        return PayResult.fail("ORDER_NOT_FOUND", "订单不存在");
    }
    // 修复:购买类型优先取页面传的值,缺省时用订单上下单时记下的来源,
    // 老页面因此也能把这笔押金交完
    String buyType = StringUtils.isNotBlank(req.getBuyType())
            ? req.getBuyType()
            : order.getBuyType();
    // 修复:实在补不齐时返回带动作的引导,客户端据此提示换一个端重新进入,
    // 而不是给用户一条看不懂的参数错误
    if (StringUtils.isBlank(buyType)) {
        return PayResult.guide("SWITCH_CLIENT", "请换一个端重新进入订单缴纳押金");
    }
    return payChannel.pay(order, buyType, req.getAmount());
}

两段代码动的是同一处:错误版把“新页面必须传购买类型”当成接口前提,缺参直接拒绝;修复版沿用同一个订单对象和同一个收款调用,只把取值改成“页面传了就用页面的、没传就用订单上的”,并在补不齐时返回可操作的引导,与正文“接口侧兜底、发布侧识别老页面”的方向一致。

下次遇到这些场景要警惕

  • 改下单、支付这类跨端流程前:把“发起端 × 支付端”的组合列全——同端新配新、同端老配老、跨端新配老、跨端老配新,每种组合各走一遍真实支付,重点看跨端那两条。
  • 给接口新增必传参数时:先列出所有会提交这个接口的页面以及它们各自的发布方式。内置离线包、H5、小程序的页面不会跟着服务端当天更新,只要还有老页面在用,必传参数就必须有服务端兜底。
  • 离线包发了新版之后:查一遍未完成更新的设备占比,找一台还是老包的设备,实际走一次关键支付步骤,确认它仍能拿到可用的结果,而不是卡在一个必传参数上。
  • 评审切换方案时:把“多端版本不同步”写成检查项,不要用“用户只会在一端操作”作为前提;跨端路径要有单独的验收用例,以及能把用户引到可用端的回退方式。