接口调用失败的排查思路

排查的起点：先区分三类现象

先把现象归类，能省一半时间。

一、完全不通

检查 1：网络连通性

从调用方服务器上测试目标地址：

• 能否 ping 通（如果 ICMP 开放）
• 目标端口是否可达
• 是否被防火墙拦截

常见情况：开发环境通了，生产环境防火墙没放行。

检查 2：接口地址与端口

核对：

• 协议（http / https）
• 域名或 IP
• 端口号
• 路径（有没有多余或缺失的斜杠）

常见情况：测试环境和生产环境地址不同，配置没改。

检查 3：认证

Token 过期是最常见的。要有自动刷新机制，且刷新失败要告警。

检查 4：服务是否在运行

对方系统的接口服务可能没启动、或正在维护。

检查：调用对方提供的健康检查接口，或联系对方确认。

二、时通时不通

检查 1：超时设置

接口超时时间设置太短，正常就会偶发失败。

判断：看失败请求的耗时，是否都接近超时阈值。

解决：适当调大超时时间，同时优化接口性能。但超时时间不能无限调大，否则会拖垮调用方。

检查 2：并发与限流

对方接口可能有 QPS 限制。超过限制会被拒绝。

检查：失败是否集中在业务高峰期。

解决：加限流控制（客户端限速）、加重试（带退避）、协商提高限额。

检查 3：连接池耗尽

如果调用方使用连接池，池大小不足时会等待，最终超时。

检查：连接池配置与监控指标。

检查 4：网络抖动

跨网络（尤其是跨公网）调用会有偶发丢包。

解决：加重试机制（必须配合幂等设计，否则会重复写入）。

三、通了但数据不对

检查 1：字段映射

两边系统的字段名和含义要对齐。

常见错误：

• 字段名相同但含义不同（比如两边的"数量"一个是订单量一个是发货量）
• 单位不同（个/箱、千克/吨）
• 时间格式不同（UTC 与本地时间）
• 编码不同（物料编码两边体系不一致）

建议维护一份字段映射表，写清楚每个字段的来源、去向、转换规则。

检查 2：必填校验

对方接口要求某些字段必填，但没传。

检查：看接口返回的错误信息，通常会指明是哪个字段。

检查 3：业务规则

接口通了，但业务上不合法。例如：

• 工单已被关闭，不能再报工
• 库存不足，不能出库
• 重复提交，被拒绝

这些会返回业务错误码，要区分系统错误和业务错误。

检查 4：数据量

如果一次传太多数据（比如一次同步 10 万条），可能：

• 请求体超限
• 处理超时
• 内存溢出

解决：分批传输，控制单批数量。

排查工具与手段

接口日志必须记录完整的请求和响应报文（敏感字段脱敏），否则出问题只能靠猜。

对账机制强烈建议加上。每天定时比对两边的关键数据（工单数、完工量、库存），不一致就告警。

不做对账，问题往往几周后才被发现，追溯成本极高。

重试的正确做法

重试是必须的，但要满足三个条件：

1. 幂等：同一次请求重试多次，结果一致
2. 退避：重试间隔递增（1s、3s、9s...），不要密集重试
3. 上限：超过重试次数后进入死信队列，人工处理

缺少幂等的重试是危险的，会制造重复数据。

一个组织层面的建议

接口出问题时，双方经常互相推诿："我发出去了" / "我没收到"。

解决办法：完整的日志 + 对账机制 + 统一的联调环境。

建议在项目初期就约定：

• 双方都要记录接口日志
• 定义统一的错误码规范
• 建立联调机制和问题响应流程
• 指定双方的接口对接人

这样出问题时，10 分钟内就能定位是哪一方的责任，而不是花两天扯皮。

接口清单与调用规范，[待补充：百华智造 MES 开放接口文档]。