企业微信接口调试全流程

三个阶段，别用同一套方法

企业微信接口调试可以清楚地切成三段，每段的目标和趁手工具都不一样。混着做的典型后果是：手调阶段过度依赖图形界面，到了线上直接抓瞎，因为线上没有按钮可点。

• 手调：验证单个接口的请求结构与鉴权是否通。工具是 Postman / Apifox / curl，目标是尽快拿到一次成功响应。
• 联调：验证完整链路，尤其是回调这一侧。工具是自己的服务加内网穿透加日志，目标是让「发出去」和「收回来」接上。
• 排障：还原一次已经发生的失败。工具只剩日志和请求标识，目标是把那一次调用从海量记录里精确捞出来。

关键判断在这里：第三段的能力必须在第一段就开始建。等线上出事再回头加日志字段，这一次事故你已经查不了了，只能等它下次发生 —— 而偶发问题的下一次可能在两周之后。这是接口调试里最贵的一课，也是本文后面两节要展开的东西。

手调阶段：把可复现性做进去

Postman 和 Apifox 都够用，选择标准不是功能条数。团队要维护一份和接口文档同步、测试同学也要用的集合，Apifox 的一体化更省事；以个人调试为主、依赖前后置脚本和复杂断言，Postman 的生态更成熟。真正决定效率的是下面这几条纪律，两个工具都适用。

• 凭证走环境变量，不写进请求本身。集合可以随便分享，环境不能 —— 这一条挡掉的是最常见的一类凭证外泄。
• 环境至少分测试和生产两套，切换时要有明显的视觉区分。对着生产环境发测试消息，是每个团队都会犯一次的错。
• 前置脚本自动取 Token，别手工复制粘贴。粘贴来的凭证过期之后，你会先怀疑接口、再怀疑参数，最后才想起它。
• 任何值得报障的问题，都要能退化成一条 curl。图形工具里「我这边点了没反应」没法交接，一条能复制粘贴的命令才行。

# -i 打印响应头（请求标识通常在这里，报障时一并带上）
# -w 拆开耗时，用来区分「服务端慢」和「握手慢」
curl -i -X POST https://manager.wecomapi.com/message/sendText \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guid":    "7db8...",
    "toId":    "78813...",
    "content": "debug ping"
  }' \
  -w '\n--- code:%{http_code} dns:%{time_namelookup}s tls:%{time_appconnect}s total:%{time_total}s\n'

最后那行 -w 经常被忽略，但它能省掉一整轮无效优化：很多「这个接口好慢」的判断，拆开之后发现慢在 DNS 解析或 TLS 握手，跟服务端处理没关系。示意里的字段与端点仅作演示，精确定义以 wecomapi 线上接口文档为准。

请求留痕：记什么、不记什么

留痕不等于「把日志打全」。全量落请求响应，几天就把磁盘写满，而且里面一定有不该落盘的东西。留痕是有选择的：记下足够还原一次调用的信息，不记还原它并不需要的内容。

每次出站调用至少记这几样 —— 请求标识（wecomapi 在响应头里回传的调用标识，站上示例里是 x-request-id，精确字段以接口文档为准）、目标接口、耗时、HTTP 状态、业务返回码、重试次数，以及你自己业务侧的关联 ID（工单号、会话 ID 之类）。最后一项最容易漏掉，也最值钱：没有它你只能按时间倒着翻，有它才能从「这个客户没收到消息」一步跳到那一次具体调用。

• 不记完整的鉴权请求头，统一打码，且打码要在框架层做。
• 不记消息正文全文。记长度和摘要足以定位，正文本身涉及用户隐私。
• 不记大体积二进制内容，记类型和大小就够。

// 示意逻辑：留痕字段在这一处定死，业务代码不各写各的
async function call(path, body, ctx) {
  const start = Date.now();
  const res = await http.post(path, body, { headers: auth() });
  log.info({
    api:      path,
    ms:       Date.now() - start,
    http:     res.status,          // 传输/协议层结果
    bizCode:  res.body?.code,      // 业务层结果，和 HTTP 状态分开记
    reqId:    pickRequestId(res),  // 平台侧请求标识，报障时要用
    bizRef:   ctx.ticketId,        // 你自己的业务关联 ID
    retries:  ctx.retries ?? 0,
  });
  return res;
}

失败响应：调试阶段先把三层记清楚

调试阶段拿到一个失败响应，先别急着查这个码什么意思，而是把它拆成三层分别记下来：有没有拿到 HTTP 响应、HTTP 状态是多少、响应体里的业务返回码是多少。压根没拿到响应和拿到一个明确的 4xx 是完全不同的两件事 —— 前者你连对方执行没执行都不知道，后者至少说明请求到达了。这三层只要有一层没记，事后就只能靠猜。

分完类之后该停、该修一次再试、该退避还是该去确认，站内讲接口报错分类那篇已经按处置动作拆得很细，这里不重复。调试阶段只需要守住一条：分类逻辑收在上一节那个包装器里统一路由，别在每个调用点各写一个 try/catch，否则同一类失败在不同调用点会得到不同待遇，而这种不一致只会在排障时才被发现。

请求标识：把一次失败从海量日志里捞出来

请求标识的作用只有一个：让你和平台方在说同一次调用。没有它，报障对话长这样 —— 「我们下午消息发不出去」「大概几点」「三四点吧」「有报错吗」「有个提示」。有它，对话是「这一次调用，这个标识，麻烦看一下」。差别不在礼貌，在定位速度。

1. 1每次出站调用，把平台返回的请求标识和你自己的业务关联 ID 写进同一条日志记录。分开记等于没记。
2. 2自己系统内部再生成一个链路 ID，从入口一路透传到出站调用，让两个 ID 在同一条记录里同时出现。
3. 3报障时给三样东西：请求标识、发生时间（带时区）、以及必现还是偶发、影响多大。有这三样和只给一张截图，不是一个量级。
4. 4回调侧同样要留痕：收到事件时把事件唯一标识记下来，它既是幂等键，也是事后回查的凭据。

偶发问题尤其依赖这套东西。偶发的定义就是你没法主动复现，只能等它自己发生 —— 那么它发生的那一刻，系统里必须已经躺好了足够的线索。这也是第一节那句话的意思：排障能力要在手调阶段就开始建，不是出事之后才建。