发生了什么

网点要开展业务,先要在签约平台上签一份合同。发起签约后,平台会建一条签约流程,流程里生成一份合同,合同带一个唯一编号;之后推进签署、查询进度,都以这个编号为准。正常情况下一笔签约只有一条流程、一份合同,编号也只有一个。

这次,一笔网点签约的流程只有一条,但平台里出现了三份内容相同的合同,编号各不相同。三份里只有一份能从流程侧查到关联,另外两份查不到对应的签约流程,也就无法继续推进。业务侧要先把有关联的那份找出来,用它推进签约,再把另外两份作废。异常出现在 7 月 30 日下午。

排查后确认,原因不在合同内容,而在生成合同时的同步重试:调用合同生成的程序给这次调用设了 5 秒超时,5 秒内没拿到返回就立刻重发,一笔签约一共发了 3 次;合同生成这一侧每收到一次请求就新建一份合同,没有按签约流程判重。

本质

签约流程和合同生成是同步串起来的:流程程序调用合同生成程序,等它返回合同编号,再把编号记到流程上。这个等待被设成 5 秒。

5 秒超时只代表这一次没等到返回,不代表对方没有处理。合同生成程序每收到一次请求就新建一份合同并返回编号,建的时候不按签约流程号判重,也不查询这个流程是不是已经生成过合同。于是每一次重发都被当成一次新的生成请求。

  1. 流程程序发起生成调用,合同生成程序新建了一份合同。这次响应没有在 5 秒内回到流程程序,流程程序判定超时。
  2. 流程程序立刻重发,合同生成程序又新建一份;再次超时,再重发一次。三次调用合计新建了三份合同。
  3. 只有拿到返回的那次,流程程序把合同编号记了下来。超时的那几次没有拿到返回,编号也就没有落回流程记录。
  4. 结果是三份合同内容相同、编号不同,流程只认其中一份;另外两份成了没有流程关联的合同,既不能推进签署,也不能自动回收,只能人工在签约平台作废。

超时只说明没拿到结果,不等于合同没有生成;把超时当失败直接重发,一笔签约就会多出几份合同。

更麻烦的是,这个重发发生在签约流程内部,流程本身并不知道合同已经建了几份。合同生成被放在这条同步调用里,等待窗口越长,重试越多,重复建单的机会就越大。这也是长期方案要把网点签约服务拆分出去的原因:把合同生成从签约流程里独立出来,单独控制超时、重试和幂等。该拆分已排进下个迭代,本次没有代码修复上线,处理方式是保留关联合同、人工作废另外两份。

修复方向是:调用方用签约流程号作为业务唯一键,每次重发都带同一个键;合同生成侧先按键查,已存在就直接返回原合同,并在合同表上对该键建唯一索引兜住并发;超时后先按业务键查一次结果,确认没生成再退避重试,不再立刻重发。

下面的 Java 代码为脱敏教学示例,用于说明“超时即重发、建单不去重”的机制与改法,不代表实际项目源码或已上线实现。

错误代码

public void generateContract(Long flowId, ContractForm form) {
    for (int i = 1; i <= 3; i++) {
        try {
            // 为什么错:只等 5 秒,超时就被当成这次生成失败
            ContractResp resp = contractClient.create(form, 5);
            // 回写编号,签约流程后续按它推进
            flowDao.bindContract(flowId, resp.getContractCode());
            return;
        } catch (TimeoutException e) {
            // 为什么错:超时后立刻重发,而建合同接口没有按流程号判重
            log.warn("create contract timeout, retry {}/3, flow={}", i, flowId);
        }
    }
    throw new BizException("生成合同失败");
}

修复代码示例

public void generateContract(Long flowId, ContractForm form) {
    // 用签约流程号做业务唯一键,重发多少次都指向同一份合同
    String bizNo = "SIGN-" + flowId;
    for (int i = 1; i <= 3; i++) {
        try {
            ContractResp resp = contractClient.create(bizNo, form);
            flowDao.bindContract(flowId, resp.getContractCode());
            return;
        } catch (TimeoutException e) {
            // 超时结果未知,先按业务键查询,确认没生成再退避重试
            ContractResp exist = contractClient.queryByBizNo(bizNo);
            if (exist != null) {
                flowDao.bindContract(flowId, exist.getContractCode());
                return;
            }
            sleepBackoff(i);
        }
    }
    throw new BizException("生成合同失败");
}

下次遇到这些场景要警惕

给“新建单据”类接口加重试时:先确认它收不收业务唯一键、服务端有没有唯一约束;在返回前人为延迟,构造“服务端已成功、客户端超时”的场景,观察重发后是不是多出了单据。

设置调用超时时间时:把超时当成结果未知,检查超时分支是先查结果还是直接重发;连续超时三次后,统计业务侧新增了几条记录、回写了几次编号。

一笔业务只应产生一个编号的流程(签约、开单、建档):用同一个业务单号并发和重复调用生成接口,核对最终单据数量和流程回写的编号是否唯一;再按“有单据、无流程关联”跑一次对账,找出孤儿单据。

看到同一笔业务出现多份相同单据时:先按创建时间排序,看它们是否集中在几秒内,再查调用方的超时和重试配置,不要先怀疑用户重复点击。