接口挂了谁先知道：WMS 集成监控告警的配置实战

先说结论：WMS 上线后第一年出的生产事故，六成跟接口有关，而接口事故里七成是"挂了几个小时没人知道"。监控告警不是上线后想起来才补的，它必须写进上线前夜 checklist，跟着接口一起交付。这一篇把我这几年见过的翻车现场讲透，再给你一份可以直接抄的配置清单。

为什么"接口挂了"这么要命

WMS 自己很少崩。数据库有备份，应用有集群，服务器挂了马上有人喊。真正恐怖的是两端都觉得"对方还在"：ERP 以为面单接口在打单，TMS 以为回传成功了，WMS 的定时任务安安静静地失败、再失败、再失败——没有告警，只有队列越积越深。

2021 年底，我在苏州一家 3PL 仓做上线。面单接口对接某快递公司，11 月 28 日上线夜一切正常，12 月 2 日凌晨 3 点，快递公司侧做了个证书续期，咱们的打单接口开始报 TLS 握手失败。WMS 这边重试三次、写失败日志、继续下一个任务——全程没有一声吭。早上 8 点，操作员发现面单停在凌晨 3 点那批，仓库门口压了 900 多个待打单包裹，司机在冷风里等了一个半小时。那天光违约金和加班，客户烧了将近两万块。其实修好它不到 10 分钟——改个证书信任配置的事。

另一次是 2023 年在东莞：电商家仓的"库存同步接口"挂了，对账失败，超卖整整 4 小时，客服被"显示有货又缺货"的投诉淹没。客服主管问我系统是不是有 bug。我说："系统没 bug，是没人盯着它。"

所以反常识的判断先扔出来：**监控不是越全越好——出事时第一个知道的必须是系统，不是客户。**你要的不是 200 个指标的仪表盘，而是半夜三点能把你叫醒的那一条告警。

分步做法：四步把监控告警配起来

第一步：先列出"必须监控"的接口清单

别监控所有接口，先保命。这五类必须配，少一类都是隐患：

打单/面单接口：挂了等于仓库停摆。这是 P0，没有之一。
出入库回传接口（ERP/TMS 回写）：挂了数据对不上，超卖、丢单从这里开始。
库存同步接口：对账类的定时任务，挂了等于盲飞。
主数据同步接口（商品/库位/供应商）：挂了不会立刻爆炸，但会慢慢腐烂——新品建不进来，旧品下不去架。
打印/硬件类接口（打印机、电子秤、扫码枪中间件）：这类最容易被忘，因为它们"不算系统接口"，但挂了现场立刻停线。

上线前夜 checklist 里加一行：这五类接口，每一个都要有对应的监控项和告警接收人，空着不许签字。

第二步：阈值怎么设——宁可吵醒你，不可错过它

新手最容易犯的错是阈值拍脑袋。我给你一套起点值，照着配，上线两周后再根据实际调：

连续失败次数：同一接口连续失败 3 次，触发告警。为什么是 3？1 次可能是网络抖动，2 次可能是对端重启，3 次基本可以确定是真出事了。
接口响应时间：平时 95 分位响应在 500 毫秒以内的接口，阈值设 2 秒；平时就 1～2 秒的重接口，阈值设 5 秒。阈值按"平时表现的 3～4 倍"设，别拍个固定数字全接口通用。
队列积压：重试队列/待处理消息超过 50 条且持续 10 分钟，告警。积压是"慢性死亡"的征兆，比瞬时失败更值得盯。
定时任务：约定执行时间过后 15 分钟还没跑完或还没开始，告警。对账、同步这类任务，"没跑"和"跑挂了"一样危险。
证书/密钥有效期：提前 30 天、提前 7 天各告警一次。苏州那个凌晨三点的事故，就是证书续期没人知道。

这些数字是建议起点值，不是标准答案。每个项目的接口表现不一样，上线后看两周监控数据再微调，原则是：误报率降到每周不超过 2 次，漏报一次都不许有。

输送线上的高架扫码器正在扫描纸箱

第三步：告警分级——不是所有事都值得半夜打电话

这个坑我见过三次：告警不分级，等于没有告警。所有告警都发短信的结果是，值班同学第三天就开始已读不回，第五天把短信设成静音——然后真正的事故来了。

分三级，规则写死：

P0 紧急（打电话+短信）：打单接口挂、回传接口连续失败、队列积压超阈值。响应要求：15 分钟内有人认领。
P1 重要（短信+企业微信/钉钉）：定时任务超时、响应时间超标、主数据同步失败。响应要求：2 小时内处理。
P2 提醒（邮件/群消息）：证书 30 天到期提醒、非核心接口偶发失败。工作日处理即可。

再加一条铁律：P0 告警如果 30 分钟没人认领，自动升级打给项目经理。值班表也要排，节假日必须有人，别指望"大家都在群里看着"。

第四步：告警发给谁——接收人清单比监控本身更重要

监控配好了，告警发到一个没人看的邮箱，等于零。我见过最离谱的一次：告警邮件发到了一个已经离职半年的实施顾问的邮箱，接口挂了两天，整个项目组没人收到。

接收人清单这么定：

每个接口指定第一责任人（通常是实施顾问或运维），再指定一个** backup**。
接收渠道至少两条：短信+即时通讯工具，P0 再加电话。
人员离职、换值班，清单当天更新，写进交接 checklist。
每季度做一次"告警演习"：故意停一个测试接口，看告警链路走没走通、接收人对不对。不演习的告警链路，等于不存在。

常见翻车点：上线前夜对照着查一遍

只监控"通不通"，没监控"对不对"：接口返回 200，但数据是空的、是错的。我见过库存同步接口天天"成功"，同步过去的全是 0——取数条件写错了。关键接口要加业务校验：回传成功后抽查一条数据，数量对不上就告警。
重试策略把雪崩藏起来了：重试 5 次、间隔 1 分钟，对端挂了之后 WMS 默默重试，日志里全是"重试中"，就是没人告警。重试和告警是两回事：第 1 次失败就记日志，第 3 次失败必须告警，别等重试耗尽。
监控了生产，忘了监控定时任务本身：定时任务调度器挂了，所有任务都不跑——但每个任务的监控都显示"上次成功"，因为根本没触发。加一个心跳监控：调度器每 5 分钟写一条心跳，超过 10 分钟没心跳，直接 P0。
告警信息写得像天书："ERROR CODE 5003"。值班同学半夜爬起来，看到这个，第一个动作是打电话问你。告警内容必须包含：哪个接口、什么问题、影响范围、第一步该做什么。模板我给你写好一个："面单接口连续失败 3 次（最后一次 03:12），影响打单作业，请检查快递公司接口状态/证书，失败日志见 xxx。"