企业系统集成：接口对接最容易踩的五个坑

过去几年我们做了不少系统集成项目，对接过 ERP、MES、财务软件和各种 SaaS。几乎每个项目都会在某个看起来简单的接口上卡住两三天。下面五个坑出现频率最高。

五个高频问题

一、字段含义不一致。对方叫“订单号”，实际是同一天的流水号，重号天天出现。对接前必须逐字段确认语义，而不是只看名字。

二、时间格式和时区。对方返回本地时间字符串，我们按 UTC 解析，数据整体偏移八小时。

三、超时与重试。对方接口平均响应三秒，我们默认五秒超时，高峰期大量失败，重试又造成重复写入。

四、重复推送。对方开启补偿机制，同一条记录可能推三次，没有幂等键就会产生脏数据。

五、状态码不统一。成功返回 200，业务失败也返回 200，只看 HTTP 状态会漏掉一半错误。

我们的对接清单

每次对接先做一份字段映射表，中文含义、类型、取值范围、是否必填全部列清，双方签字确认。

在联调环境模拟三类异常：超时、重复、部分成功。这三类跑通，上线才比较安心。

集成项目的成败往往不取决于技术难度，而取决于双方对同一句话的理解是否一致。