请求 ID 是 API 在每个响应标头中返回的唯一标识符;联系支持时,可据此在提供商日志中找到特定调用。
调试横跨两家公司的集成,需要一个双方共用的标识。请求 ID 就是这个标识:服务器为每次 HTTP 交互生成一个唯一值,并在响应标头中返回,按照惯例,该标头通常名为 X-Request-Id。把它提供给提供商的客服团队,他们就能准确找到收到了什么、何时收到、又作了什么答复,而无需按时间戳在成千上万次相似的调用中搜索。
把这几种标识符区分清楚会很有帮助。请求 ID 标识一次交互。资源 ID(例如消息 ID)标识所创建的对象,它的存续可能跨越许多个请求:一个超时后使用同一幂等密钥重试的 POST,会产生两个请求 ID 和一条消息。关联 ID 则由你自己掌握:在你系统的边缘生成,并随任务经过的每个服务一路传递;W3C Trace Context 等追踪标准把同样的思路在跨服务场景中规范了下来。请把它们一起记录下来,并附上端点、HTTP 状态码和 UTC 时间。
示例
假设一个订单服务在 UTC 时间 14:02:11 收到一个 500 响应。它的日志行中记录了响应里的请求 ID、幂等密钥、端点和状态码。支持工单只需引用这个请求 ID,无需其他任何信息:不用截图,不用粘贴满是电话号码的有效载荷,也不会意外暴露 API 密钥。
常见错误
- 只在成功时记录响应标头,而真正需要它们的恰恰是出错的时候。
- 让 HTTP 客户端在读取标头之前就抛出异常。
- 询问某条消息的送达情况时,把请求 ID 和消息 ID 混为一谈。
在 SMSMeteor:每个响应都带有 X-Request-Id;联系客服时请附上该值,客服每周七天在控制面板中回复对话。标识符都带有前缀:msg_、bat_、evt_、cmp_。reference 字段可容纳最多 128 个由你自定义的字符,会在响应和 Webhook 中原样返回,因此可直接用作现成的关联 ID;重放的 Webhook 事件保留其原始事件 ID。请参阅 API 参考。
