对接第三方接口的六个坑，每一个都让工期多三天

"接个支付接口，一天能搞定吧？"——实际平均三天，遇到坑一周。这不是开发水平问题，是第三方接口的固有复杂度。

坑一：文档和实际不一致

字段名拼写不同、必填项没写、返回结构在错误时完全变样。应对：第一步不是写业务代码，而是先把对方所有接口跑通一遍，成功和失败的返回都截图存档，做成自己的接口笔记。

坑二：签名算法

参数排序规则、是否 URL 编码、空值参不参与签名、时间戳精度——任何一处不同，签名就错。而且报错信息通常只有"签名错误"四个字。

应对：让对方提供官方 SDK 或示例代码，直接跑通示例，再改成自己的业务。自己从零实现签名，是最容易浪费时间的做法。

坑三：异步回调

支付、退款、物流都是异步通知。三个必备动作：验签（防伪造）、幂等（同一笔通知可能来多次，不能重复扣款/发货）、返回规定格式（没返回正确格式，对方会一直重试，重试几十次后放弃，你的订单就卡住了）。

坑四：超时与重试

没设超时的请求会一直挂着，占满线程池，整个服务卡死。所有外部调用都必须设超时（连接 3 秒、读取 10 秒是常见配置），并且区分"可重试"和"不可重试"错误——支付超时不能盲目重试，会造成重复下单。

坑五：沙箱与生产不一致

沙箱环境一切正常，切到生产就报错：证书不同、商户号不同、IP 白名单没加。上线前一定要在生产的测试金额（比如 0.01 元）跑一遍完整流程，包括退款。

坑六：额度与限流

短信接口每天有上限、地图接口有 QPS 限制、发票接口有调用频次。没做限流和降级，高峰期直接被封。应对：本地做频次控制 + 缓存 + 失败告警。

我们的标准做法

• 所有第三方调用集中在一个适配层，换供应商只改这一个文件
• 每次调用记录请求、响应、耗时到日志表，出问题能直接查
• 关键接口做熔断：连续失败 N 次自动暂停，避免雪崩
• 上线前跑一份"异常场景清单"：超时、返回空、返回错误码、重复回调

这套东西做完，对接一个新接口大约是 2 – 3 人天，而不是"一天搞定然后修一周"。