代码实战：从对接第三方API谈如何写健壮性的代码

我这边的业务系统里有一个业务场景业务单据需要实时同步到第三方的低代码平台各个合作方的客户在低代码平台上对这些单据做发货、审核等操作。如果某张单据同步失败了客户在平台上看不到就是大故障。对接低代码平台需要通过它的OpenAPI来写入和查询数据。问题在于调第三方接口不像调自己的内部服务那么可控。超时了、连接断了、返回了500了各种意外情况都可能发生。而且调用失败不代表真的失败对方可能已经处理完了只是响应在回来的路上丢了。对接第三方API怎么保证代码足够健壮这里用一个真实的业务场景以及实际的代码来说明一下。统一调用入口低代码平台的接口设计通常比较统一写入数据用addRow更新数据用updateRow查询数据用getRows。不管你是同步哪种业务单据底层调的都是这几个方法。项目里需要有一个人把这些接口封装好写一个LowCodeClient类团队里其他人直接调addRow、updateRow就行不需要关心HTTP请求怎么拼、网关怎么走、响应怎么解析。这个统一入口的好处不只是省事。调用入口统一了监控可以加在这里日志可以记在这里异常处理也可以在这里统一做。如果每个业务模块各自对接低代码平台的接口代码分散在各处出了问题排查起来非常困难也没法统一加降级和重试逻辑。LowCodeClientImpl里所有的写入操作最终都走一个exec方法GatewayRequestDTOreqbuildRequest(apiName,appType,body);JSONObjectrespJSON.parseObject(callGateway(req,apiName));ObjectdatacheckResponse(apiName,resp);returndata!null?data.toString():null;buildRequest负责拼装请求参数callGateway负责发HTTP请求checkResponse负责校验响应结果。低代码平台的API响应里有个success字段为false的时候直接抛异常上层调用方通过catch来感知失败。调用失败不代表真的失败这是对接第三方系统时最容易踩的坑。调用addRow往低代码平台写数据返回超时了或者网关报错了。很多人第一反应就是写入失败直接报错。但实际上请求可能已经到了对方那边数据已经写进去了只是响应没回来。在生产环境里这种事发生的频率比想象的高。网络抖动、对方服务重启、网关超时都可能导致你拿不到正确的响应但对方其实已经处理了你的请求。所以一个基本的原则是addRow失败了先别急着判定结果去查一下再说。查询确认低代码平台一般都有查询接口支持按业务单据号查记录。当addRow抛异常的时候不是直接当失败处理而是先调查询接口拿单据号去查数据到底写进去没有查到了说明写入其实成功了只是响应丢失了业务继续往下走。没查到那才是真的失败了进入下一步处理。这一步很多人会忽略。觉得调用报错了就是失败了重试一下就行。但如果对方其实已经写进去了你再重试写入一次就可能出现重复数据。虽然有些平台会根据幂等机制帮你挡住但不能把希望寄托在对方的实现上。重试一次确认是真的失败了可以重试。但只重试一次。为什么是一次如果是临时的网络抖动一次重试大概率就能成功。如果重试一次还是失败说明对方系统大概率是真的有问题可能是服务挂了可能是接口出了bug。这种情况下你重试三次五次也没用只会让当前请求卡在那里等半天拖慢整个系统的响应速度。快速失败把问题交给后台去处理比让实时请求一直在那里死等要合理得多。写入任务表兜底重试一次还是失败了这时候不能再继续重试了。但数据不能丢需要有一个兜底机制。做法是往biz_task表里写一条记录包含任务名称、业务单据号、业务类型等信息。后台有调度程序会按照阶梯式的时间间隔自动重试这些任务1分钟、5分钟、30分钟、2小时。随着对方系统恢复大部分任务会自动重试成功。如果所有重试都失败了系统会把告警信息推送到告警群让人工介入。biz_task表的结构CREATETABLEbiz_task(idBIGINTUNSIGNEDAUTO_INCREMENTPRIMARYKEY,nameVARCHAR(400)NOTNULLCOMMENT任务名称,typeVARCHAR(100)DEFAULTNOTNULLCOMMENT任务类型,biz_idVARCHAR(200)DEFAULTNOTNULLCOMMENT业务ID,biz_typeVARCHAR(100)NOTNULLCOMMENT业务类型,retry_countINTUNSIGNEDDEFAULT0NOTNULLCOMMENT重试次数,execute_resultVARCHAR(20)COMMENT执行结果,statusVARCHAR(20)DEFAULTNOTNULLCOMMENT状态,trigger_timeTIMESTAMP(3)COMMENT触发时间,priorityINTDEFAULT0NOTNULLCOMMENT优先级,create_timeTIMESTAMPDEFAULTCURRENT_TIMESTAMPNOTNULLCOMMENT创建时间,update_timeTIMESTAMPDEFAULTCURRENT_TIMESTAMPNOTNULLONUPDATECURRENT_TIMESTAMPCOMMENT更新时间)COMMENT业务任务;这个任务表是我自己封装的一个轻量级业务task框架专门处理这类失败后需要异步重试的场景。没有引入消息队列的延迟消息也没有用定时任务框架就是一个简单的任务表加调度程序够用也足够可控。这块后面有时间会专门写一篇来分析。完整流程把上面的逻辑串起来整个单据同步的健壮性处理链路是这样的先通过统一的LowCodeClient调用addRow写入单据。如果写入成功正常返回rowId业务继续。如果写入抛了异常先别慌调低代码平台的查询接口拿单据号查一下。查到了说明其实成功了返回已有的rowId。没查到确认是真的失败了重试一次addRow。重试成功正常返回。重试还是失败写一条biz_task记录返回null。用一段代码来表达try{rowIdlowCodeClient.addRow(SHEET_ID,APP_TYPE,controls,false);}catch(Exceptione){rowIdlowCodeClient.queryRowIdByBizNo(SHEET_ID,docNo);if(rowIdnull){try{rowIdlowCodeClient.addRow(SHEET_ID,APP_TYPE,controls,false);}catch(ExceptionretryEx){// 写入失败任务由后台调度阶梯重试saveRetryTask(docNo,docType,controls);}}}整个流程的逻辑是不信任任何一次调用的结果失败了先查询确认确认不了就交给后台任务慢慢重试重试到最后还是失败了则将告警信息同步到专门的监控群人工介入处理。。实际项目里低代码平台的接口偶尔会因为升级、网络波动等原因出现短暂不可用。如果没有这套机制一次接口抖动就可能导致一批单据同步丢失客户那边直接投诉过来。有了这套机制大部分同步失败都能在后台自动恢复真正需要人工介入的情况很少。小结对接第三方API代码层面的东西其实只是表象背后的思考方式才是关键。程序员之间的水平差距很多时候不体现在能不能把功能实现出来而体现在会不会主动去想那些不会出现在需求文档里的异常场景。网络超时了、对方返回了假成功、重试还是失败、服务突然挂了这些问题不在需求里写着但每天都在生产环境里发生。对接第三方系统是最能体现这个差异的场景。你没法控制对方的行为对方什么时候升级、什么时候重启、什么时候出bug你完全不知道。你唯一能做的就是在自己这一侧把所有可能的异常情况都考虑到每一种异常都有对应的处理策略。程序不能一遇到异常就撂挑子不干而是要有层次地应对先确认、再重试、再兜底、最后告警。充分考虑非功能性需求是高级程序员和普通程序员之间一个重大区别。功能实现只是及格线在各种异常场景下系统仍然能稳定运行才是真正有水平的体现。这种思考习惯不是看几篇文章就能学会的需要在真实的项目里反复踩坑、反复总结才能慢慢形成直觉和习惯。