发生了什么

网点要开展业务,先要签一份合作合同。网点在后台重新提交签约,审批通过后,系统为这次签约建一条合同记录,并给合同创建程序发一条消息,消息里只带这条记录的编号。合同创建程序按编号把记录取出来,再从记录里取“更新人”——也就是最后操作这条记录的人——拿这个人的身份去员工目录里查工作邮箱。创建请求要带上经办人的工作邮箱,外部电子签约平台按这个邮箱识别经办人,经办人的账号没开通,创建就会被拒绝。正常情况是一条签约对应一份合同,建好后把合同编号回写到记录上,签约流程继续往下走。

这次,经办人还没有在外部签约平台开通账号,第一次创建请求被对方拒绝,系统把这笔记成创建失败,同时发了提醒。经办人随后开通了账号,看起来障碍已经消除。但网点再次提交签约,被“已有合同在审批中”的校验拦下;运营在消息平台手动重发那条消息,重试依旧失败,合同还是建不出来。最后只能人工订正这条合同记录的数据,重试才成功。

确认到的范围是一个商户、一个网点。因为创建失败有即时提醒,出现后很快就有人跟进,没有长期拖着网点。

本质

问题不在外部接口,而在失败处理顺手改了“更新人”。重试取邮箱用的正是这个字段,被改掉之后,重试连经办人都找不到了。

  1. 第一次创建时,外部平台拒绝请求。合同创建程序捕获异常,把这条记录标成失败,同时把更新人改成系统账号,用来表示“这次变更是系统写的”。这一步在代码里看着只是留痕。
  2. 记录本身还停在“合同未创建”,签约流程也还挂在这条记录上,等着同一个编号再跑一次创建。
  3. 经办人在外部开通账号后,运营手动重发同一条消息,消息里还是那个记录编号。合同创建程序重新按编号取记录,取出的更新人已经是系统账号。
  4. 程序拿系统账号去员工目录查邮箱,员工目录里没有这个账号,返回空。程序在调用外部接口之前就抛错退出,所以这一次重试连请求都没发出去,外部问题是否已经解决根本没有被验证到。
  5. 网点自己再提交一次签约也不行:系统认为这条签约的合同还在审批中,把新提交挡在前面。两条路都被堵住,只剩人工把更新人订正回经办人,重试才能继续。

失败处理改写了重试所依赖的字段,于是“外部问题已经修好”和“重试永远跑不过去”同时成立。

修复方向是:失败分支不再改写更新人,只更新失败状态和失败原因,更新人继续由真实操作人写入。这样重发消息时还能取到经办人,重试就可以重新调用外部接口。记录里的临时处理是人工订正这条记录的数据;代码修复的上线与验证状态待确认。

下面的 Java 代码为脱敏教学示例,用于说明“失败分支覆盖更新人,导致重试取不到经办人”的机制与改法,不代表实际项目源码或已上线实现。

错误代码

// 合同创建程序:消息里只有记录编号,经办人从记录里取(示意)
public void createContract(Long contractId) {
    ContractRecord record = contractDao.selectById(contractId);
    // 为什么错:经办人邮箱是从“更新人”推出来的,
    // 这个字段一旦被失败分支改写,重试就再也取不到当初的经办人
    String email = staffDirectory.findEmail(record.getUpdater());
    if (email == null || email.isEmpty()) {
        throw new BizException("经办人邮箱不存在,创建合同中止");
    }
    externalSignClient.create(record.getSignNo(), email, record.getForm());
    contractDao.markCreated(contractId, externalSignClient.lastContractNo());
}

// 失败处理,由同一个消费逻辑在捕获异常后调用
private void onFailed(Long contractId, Exception e) {
    // 为什么错:为了标记“这次失败是系统记的”,把更新人写成系统账号,
    // 顺手覆盖掉了重试唯一能定位经办人的字段
    contractDao.updateUpdater(contractId, "sys");
    contractDao.markFailed(contractId, e.getMessage());
}

修复代码示例

public void createContract(Long contractId) {
    ContractRecord record = contractDao.selectById(contractId);
    String email = staffDirectory.findEmail(record.getUpdater());
    if (email == null || email.isEmpty()) {
        // 取不到人时明确报出字段值,便于判断是数据被改写还是账号缺失
        throw new BizException("经办人邮箱不存在,更新人=" + record.getUpdater());
    }
    externalSignClient.create(record.getSignNo(), email, record.getForm());
    contractDao.markCreated(contractId, externalSignClient.lastContractNo());
}

private void onFailed(Long contractId, Exception e) {
    // 只记录失败状态与原因,不改写更新人,重发消息时仍能取到经办人
    contractDao.markFailed(contractId, e.getMessage());
    alert.warn("contract.create.fail", contractId, e.getMessage());
}

下次遇到这些场景要警惕

  • 给失败分支加“留痕”写操作时:先列出重试链路会读哪些字段(更新人、归属人、状态、经办人),确认失败分支不写这些字段;构造一次外部失败再重发,观察重试取到的还是不是原来的经办人。
  • 重试要靠“再查一次记录”拿上下文时:用同一个编号连续重试两次,比对两次读到的关键字段值;只要第二次和第一次不同,就要查中间是谁写了它。
  • 外部系统报错后恢复:对方恢复后先手动重发一次消息,看真实结果;不要只用页面重新提交,页面可能被“流程进行中”的前置校验挡住,掩盖重试通道本身的问题。
  • 排查“重试一直失败”时:先看失败分支对记录做了什么写操作,再看重试读回了什么,不要先怀疑外部接口还没恢复。