发生了什么
平台在线下开经营点位,每个点位都要和场地方签租赁合同:租哪块场地、租多久、租金怎么算都写在这份合同里。合同到期要续租,续租是重新发起一份新合同,同样走审批和电子签署。
合同不在自己的系统里生成。内部合同程序先建一条合同记录,审批通过后再调用外部电子签约平台创建合同;平台返回一个合同编号,程序把编号写回记录、状态推进到“签约中”,双方盖章后平台回调再改成“已签约”。业务就看签约页面上这条记录,判断点位能不能继续开店、续租。
正常顺序是:审批通过、调用平台创建、拿到编号回写、推进状态,盖章完成再改已签约。审批通过只代表允许去创建,编号回来才代表平台那边真有这份合同。
这次是一份个人房东的续签。创建调用被平台以“请求过多”拒绝,合同一次都没建成。本地记录停在“审批中”这个中间状态——审批已经过了,只是没有拿到合同编号,状态推进不下去——合同编号为空,扩展数据里多了一条错误标记,页面显示“合同签约异常,请联系业务”。
业务看到提示,去平台里找待签约的合同,一份也没有,于是判断合同丢了,要求作废后重新发起。可平台里没有可作废的对象:合同从没创建出来,本地记录也走不到作废分支。同一时段还有几条同类续签被一起拒绝,是批量集中重试撞上了平台的频率限制。
本质
一句话:创建合同的调用被限流打回,程序当成永久失败直接抛出;而那条用来补编号的回查消息在这之前就排好了,它要查的合同从没创建出来。
- 正常流程下有三步:调用平台创建、把返回的编号写回记录、把状态推进到签约中。三步都完成,本地和平台才是同一份合同。
- 这次第一步就被拒。平台对短时间内的集中请求做了频率限制,返回“请求过多”。这类拒绝是暂时的,同样的请求隔一会儿再发通常就能通过。
- 程序不是这么处理的。调用之前它先发了一条延迟三分钟的回查消息,打算到点问平台“合同建好了吗”;发完才看结果,发现失败就抛业务异常结束,既没有退避重发,也没有别的程序接手。
- 回查到点,程序按发起时写下的来源编码去平台查合同。平台没有这条编码的数据,返回“数据不存在”。
- 回查程序把“查不到”当成异常结果,往扩展数据里写错误标记,页面再把它渲染成“合同签约异常,请联系业务”。
- 两条路同时断掉:创建没成功,回查只能证明平台没有这份合同。记录没有合同编号、没有在重试的任务,停在中间状态。
- 误判由此而来:“签约异常”像签了一半,平台又找不到待签约,于是被理解成要作废重发。可平台没有对象可作废,本地也没有编号可推进,只能人工补。
回查在创建结果出来之前就发了出去,创建失败后它照样到点执行,能查到的只有“查无此合同”;错误标记把“从未创建”写成了“签约异常”,把业务引向走不通的作废重发。
处置是人工补的:重新调用创建接口在平台建出合同(生成新的来源编码),再手动发一条查询消息按新编码回查,把编号回填到记录、状态推进到签约中;验证结果是编号回填、页面不再显示异常,之后等盖章回调改成已签约。修复方向是:限流这类临时拒绝改为退避重建;回查消息挪到创建成功之后;对“状态在途、编号为空”的记录做对账补建。修复是否上线并验证,记录里没有结论。
错误代码
public void createAfterApproval(long recordId) {
ContractRecord record = recordMapper.selectById(recordId);
// 为什么错:调用还没发就先把回查排上,创建失败时这条回查照样会到点执行
mq.sendDelay(QUERY_CONTRACT_TOPIC, buildQuery(record.getSourceCode()), 180);
OneContractResp resp = oneContractClient.createPersonContract(record);
// 为什么错:限流(临时失败)和参数错误(永久失败)走同一分支,一律抛出
if (!resp.isSuccess()) {
throw new BizException("外部签约调用异常:" + resp.getMessage());
}
recordMapper.updateContractNo(recordId, resp.getContractNo());
recordMapper.updateStatus(recordId, CONTRACT_SIGNING);
}
public void onQuery(ContractQueryMsg msg) {
ContractDetail detail = oneContractClient.queryBySourceCode(msg.getSourceCode());
if (detail == null) {
// 为什么错:查不到就写错误标记,页面据此显示“合同签约异常”
recordMapper.updateErrorCode(msg.getRecordId(), "SIGN_CREATE_FAILED");
return;
}
recordMapper.updateContractNo(msg.getRecordId(), detail.getContractNo());
}
修复代码示例
public void createAfterApproval(long recordId) {
ContractRecord record = recordMapper.selectById(recordId);
OneContractResp resp = oneContractClient.createPersonContract(record);
if (!resp.isSuccess()) {
if (resp.isRetryable()) {
retryQueue.enqueue(recordId, nextBackoff()); // 限流等临时失败:退避后重建
} else {
recordMapper.markCreateFailed(recordId, resp.getMessage()); // 明确拒绝:交人工
}
return;
}
// 创建成功后才落编号并发回查,回查对象一定存在
recordMapper.updateContractNo(recordId, resp.getContractNo());
recordMapper.updateStatus(recordId, CONTRACT_SIGNING);
mq.sendDelay(QUERY_CONTRACT_TOPIC, buildQuery(recordId, resp.getSourceCode()), 180);
}
public void onQuery(ContractQueryMsg msg) {
ContractDetail detail = oneContractClient.queryBySourceCode(msg.getSourceCode());
if (detail == null) {
retryOrEscalate(msg); // 查不到按次数退避重查,超限进人工队列并告警
return;
}
recordMapper.updateContractNo(msg.getRecordId(), detail.getContractNo());
}
代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。修复版沿用同一入口与同一对象,只改两处:把限流这类临时失败从“创建失败”里分出来走退避重试;把回查消息挪到创建成功之后。后一处同时去掉了“回查一个不存在的合同”这种必然失败的调用,但平台侧在履约期间出现的其它异常仍需对账兜底。
下次遇到这些场景要警惕
- 给“先调外部接口、后补延迟消息”的流程加分支时:先写下两次调用的先后顺序,再用一次“请求过多”的响应跑一遍,观察回查是否仍被发出、它要查的对象是否真的存在。
- 处理外部接口的失败返回时:把限流、超时和参数错误分成两类,构造一次限流响应,看是否排了带退避的下一次调用、失败次数是否真的在涨;只有一行异常日志不等于做了重试。
- 排查“页面提示签约异常、平台里查不到合同”时:按来源编码比对两端。平台查无此合同说明创建工作根本没成,不能按“签了一半”去作废重签;两端都有合同而本地编号为空,才是回查没写回。
- 批量任务集中重试外部接口时:造一次同批大量记录一起重跑的场景,看响应里是否成片出现限流;出现就说明缺并发上限或退避,应先在批量入口收敛速率。