企业微信接口开发的工程规范

值得写进文档的规范只有四条

团队立接口规范最常见的结局是写了三十条、守住两条。原因不复杂：大部分条目挡不住任何具体的痛。缩进风格错了没人受伤，格式化工具十秒钟解决；而真正会疼的地方，一条都没写。

判断一条规范该不该写，只用一个标准 —— 它能不能挡住一次「改一处要改一百处」。按这个标准筛，企微开发接口这件事上值得写的就下面四条，其余的交给 linter 和 code review。

• 封装边界：平台的字段形状允许出现在哪一层，不允许出现在哪一层。
• 错误建模：失败按「谁去修」分类，不按返回码在业务代码里分支。
• 日志分层：排障、审计、指标是三种东西，不要写成一条流。
• 配置外置：会变的东西不进代码，变更频率不同的配置不放一处。

封装边界：三层，缺一层和多一层都要付账

把接入代码切成三层：接入层负责鉴权、超时、重试与留痕，一个进程只有一份；能力层把每个业务动作封成一个函数，出入参用你自己的类型；业务层只认能力层的函数，不知道 HTTP 长什么样。分层怎么切、依赖方向怎么定，站内讲二次开发分层那篇是专门讲这个的；写进规范的只需要一句可判定的话 —— 平台的字段形状只允许出现在能力层以内，越过这条线就是违规。

多数团队只做了一半 —— 请求封了，响应没封。平台返回的结构原样传到业务层，业务代码里到处是对返回体的取值和判空，这等于没封：换个接入方式，或者返回结构多一层嵌套，改动照样铺满整个代码库。能力层的职责是双向的，进去收敛一次，出来也要收敛一次。

// 示意逻辑：端点与字段以 wecomapi 文档为准，这里只表达分层结构
export async function sendText({ accountId, to, text }) {
  const res = await transport.post(
    "https://manager.wecomapi.com/message/sendText",
    {
      guid:    accountId,   // 入参在这一层映射成平台形状
      toId:    to,
      content: text,
    },
  );
  return toSendResult(res); // 出参也收敛，业务层拿到的是你自己的类型
}

// 业务层只写这一行，并不知道上面那个 URL 存在
await sendText({ accountId, to: customerId, text: "工单已受理" });

封装时机也有一条能直接用的经验值：第三个调用点出现时再封。只有一个调用点时封装是纯成本，到了第三个，复制粘贴的那几份差异已经开始跑偏。用 wecomapi 这类统一 REST 语义接入时这条尤其成立 —— 各能力共用同一套请求结构与错误模型，能力层写起来很薄，薄到没有理由不写。

错误分类：按「谁去修」分，不按返回码分

失败按现象怎么认、各自的正确反应，站内讲接口报错分类那篇已经拆完了，这里不重讲一遍。规范这一侧要定的是另一件事：每一类失败必须有一个明确的归属人。归谁修决定告警发给谁，也决定这次要不要重发 —— 顺序反过来，就会出现「该叫人的时候在默默重试」。

1. 1归开发：参数缺失、结构不合法、调用了不该调的动作。
2. 2归运维或管理员：凭证失效、能力范围不覆盖、回调地址不可达 —— 代码没问题，告警要发给能改环境的人。
3. 3无人认领，等一会儿即可：频控、上游抖动、瞬时容量不足。
4. 4归人工队列：账号登录态异常、业务状态冲突，比如目标对象已不在可操作范围。

这四类要在能力层就转成你自己的错误类型抛出去，业务层不允许出现对平台返回码的分支判断。理由和上一节一样：返回码是外部契约，让它渗进业务代码，你就永远换不掉接入方式；顺带还有一个好处 —— 自有错误类型可以在单元测试里直接构造，平台返回码不行，第四类错误你根本没法在测试环境里造出来。

日志：三种用途，三条流

「日志要打全」是句没有信息量的话。日志有三种互不兼容的用途，混在一条流里写，结果是三种都不好用。

• 排障日志：高基数、字段多、可采样、保留几天。目标是还原一次调用到底发生了什么。
• 审计日志：低频、字段固定、不可采样、不可事后修改、保留期由合规决定。目标是回答「谁在什么时候动了什么」。
• 指标：只有聚合数值和低基数标签，不含任何用户内容。目标是发现趋势，不是定位个案。

混流的后果很具体：为了省成本给日志加采样，审计记录被采掉一半；或者把请求标识打进指标标签，监控系统的基数直接炸掉。这三条流从第一天就该分开写 —— 后面合并容易，拆开难。

接口开发这一侧还有一条常被漏掉的：出站调用和事件回调要用同一个链路标识串起来。用 wecomapi 的事件回调拿到消息后，处理链路是固定的 —— 先快速 ACK，再入队异步处理；链路标识必须跟着事件穿过队列走到消费端，否则日志会在队列那里断成两截，你只看得到「收到了」，看不到「后来怎么了」。

最后一条纪律关于级别：error 的定义是「需要有人今晚处理」，达不到这个标准的一律降级。这条守不住，告警池会被自己淹掉，和没有告警等价。

配置管理：按变更频率分三档

配置按「跟谁走」分成结构、环境、机密三类，站内讲多环境管理那篇已经切过一刀。接口开发这一侧还要再补一条正交的切法：按变更频率分档。这两刀不冲突 —— 前者决定配置存放在哪，后者决定它允许被改得多快。

1. 1环境级：端点、凭证、回调地址。几个月不变，随环境走，绝不进代码仓库，也绝不进日志。
2. 2账号级：账号实例与业务线、回调路由、限速档位的绑定关系。这一档的条目数会增长，超过五个就该进数据库当业务数据管，不要继续当配置文件维护。
3. 3策略级：限速值、重试次数、功能开关、灰度比例。这一档必须支持不重启修改 —— 线上被频控的时候，改一个数就能止血，重启一次可能要十分钟。

账号级那一档最容易被低估。单账号接入时它看起来只是两行配置，多账号之后每个实例的凭证、回调路由和限速档位都要独立管理。在 wecomapi 上以账号为订阅单位时这一点更明确：账号是有生命周期的资源，会新增、会停用、会换绑，而配置文件天生不擅长表达生命周期，数据库擅长。

策略级配置还有一条容易翻车的：功能开关要带下线日期。没有下线日期的开关会一直留着，两年后没人记得它控制什么，也没人敢删 —— 于是每次改动都要多考虑一个分支。加开关的那个 PR 里就把清理时间写进注释，是成本最低的做法。