企业微信协议 SDK 与开发框架

三个检索词，底下是两类东西

「企业微信协议SDK」「企业微信协议开发框架」「企业微信协议框架」几乎指向同一个诉求，但底下压着性质完全不同的两类东西，混着讨论必然吵不出结果。

• 库，也就是语言绑定：对着一套已有的 HTTP 接口做的薄封装，帮你省掉拼请求、解响应、映射错误。它不改变你的程序结构 —— 你调用它。
• 框架：带事件循环、消息路由、插件机制、生命周期钩子的运行时。它会改变你的程序结构 —— 它调用你。
• 还有第三样东西不在网上：你自己那层内部客户端。它只服务一个项目、随业务演进，每个跑起来的系统里都有，只是很多团队没意识到自己已经写了一个。

三者的结论差得很远：库可有可无，取决于调用点数量；内部客户端必须有，问题只是写得糙还是写得稳；框架是唯一一个需要认真决定的，因为它一旦进来就很难退出。下面按这个顺序过一遍。

库这一层：判据是样板代码抄了第几遍

该不该引一个语言绑定、或者自己封一个，取决于一个很俗但很准的指标：你的代码里有多少个不同的调用点，以及同一段样板代码你抄了几遍。

该不该封、什么时候封，站内讲 SDK 选型那篇已经按调用点数量和团队规模给过一条判断线，这里不再重讲。只补一条和「库」这个形态直接相关的：调用点还少的时候，封装挡住的恰恰是联调期最有价值的材料 —— 原始请求与响应报文。这个阶段直接发 HTTP、把完整报文打进日志，比任何封装都管用。

越过这个量级，或者出现了有状态语义 —— 分页游标、批量任务的分片、长耗时操作的结果轮询、需要统一退避的重试 —— 封装才转正。抄第三遍的时候抽出来是对的，抄第一遍就抽是过度设计。

还有一条经验：接口形态越统一，这层越薄。对着 wecomapi 这类统一鉴权、统一错误模型的接口写协议层，通常一两百行就够 —— 鉴权是一个请求头，错误映射是一张表，分页语义只有一套。真正会把这层撑大的，是有多套鉴权、多种响应结构要抹平的场景。

// 示意代码，端点与字段仅表达调用形态，精确定义以线上接口文档为准

async function call(path, body, opt) {
  const res = await fetch("https://manager.wecomapi.com" + path, {
    method:  "POST",
    headers: {
      Authorization:  "Bearer " + opt.token,
      "Content-Type": "application/json",
    },
    body:   JSON.stringify(body),
    signal: opt.signal,        // 超时由调用方传入，协议层不替业务决定
  });

  const data = await res.json();
  if (!res.ok || !isOk(data)) {
    // 原始响应体、状态码、调用标识一起带出去，别只抛一句字符串
    throw new ApiError(data, res.status, opt.traceId);
  }
  return data;
}

// 领域层认识业务动作，业务代码认识领域层，谁都不认识 path
const sendText = (guid, toId, content, opt) =>
  call("/message/sendText", { guid, toId, content }, opt);

注意这段里协议层既没有做重试，也没有自己决定超时。这不是省事，是刻意的 —— 理由在下一节。

框架这一层：代价是控制反转

框架和库的区别只有一句话：库是你调用它，框架是它调用你。这句话听着像术语区分，落到工程上是很硬的成本 —— 并发模型、事件循环、重试时机、错误传播路径全由框架决定，你的限流、幂等、可观测都得迁就它给出的钩子。有钩子还好，没有就只能改源码或者绕过它，两条路都不体面。

三个最常见的疼点，都不是框架写得差，而是职责放错了层。

1. 1幂等落错层。幂等必须做在产生副作用的那一层；框架如果把重试藏在内部，那一层就在框架里面，你在外面加的去重形同虚设，表现为「明明做了幂等还是发了两条」。
2. 2限流维度对不上。框架通常按连接或按账号限流，而实际需要的往往是按会话分桶 —— 一个刷屏的群不能把其它会话的配额吃光。维度不匹配时，配置项加再多也调不出想要的行为。
3. 3可观测断链。框架有自己的日志格式和上下文传递方式，和你的 trace 体系对不上。结果是一次请求在你的链路里有标识、进了框架就断了，排障只能靠时间戳猜。

还有一笔不那么技术但更现实的代价：升级。框架是一条你必须持续跟进的外部依赖，它每次发版都可能要求你改处理函数签名或者配置结构，而这件事产生的业务价值是零 —— 你只是把系统维持在原地。评估时把这笔年度开销算进去，结论经常会反过来。

什么时候框架确实划算

上面全是代价，但框架不是不该引。它解决的是一类真问题：调度。下面这几件事只要同时出现两条以上，自己写调度层的成本就会明显超过迁就框架的成本。

• 要同时跑多个账号的机器人，它们共享一套业务逻辑，却各自有独立的速率预算和运行状态。
• 有跨多轮的长流程状态机，会话上下文要持久化、要超时回收、要能中途取消。
• 多租户隔离：配置、话术、数据都按租户分开，而且租户数量是会长的。
• 团队里确实没人愿意长期维护那套调度逻辑。这条比前三条更常见，也是个正当理由，不用不好意思写进技术方案。

反过来，什么时候不值得：如果你只是用 wecomapi 的 REST 接口发消息、收回调、跑几条规则，两个文件就够了。这种规模引框架，换来的只是别人的目录结构，外加一份需要跟进的升级日志。

不管引不引，这一层必须是你自己的

领域层没有第二个选项。「给这个会话发一条文本」「把这个客户标记成已跟进」表达的是你的业务模型，不是接口形状。这层如果不写，业务代码里就会直接出现请求路径和外部字段名，后果是换供应商、跟版本升级都退化成全仓库搜索替换。它不需要写得漂亮，只需要存在。

用 wecomapi 这类以 REST 为主的接口时，这层尤其好写：一个业务动作基本对应一次调用，领域层不需要在里面做多接口编排，本质上就是一组命名良好的函数。写起来快，反倒容易被跳过 —— 而跳过的代价要到第一次换接口或者第一次跟版本时才结算。

一个五秒钟的自检：在业务代码里搜一遍 http，再搜一遍任意一个外部字段名。搜得到，说明领域层没有真正建起来，前面几层做得再好也不算数。

内部客户端该封哪些横切逻辑、又不该封什么，站内讲 SDK 选型那篇列过一份清单，这里不重复。只补两条和「要不要引框架」直接相关的 —— 它们决定了框架进来之后，重试和排障还在不在你手上。

1. 1超时和重试策略由调用方传入，且默认不自动重试。这一条正是上一节那个幂等疼点的反面：只要重试的时机由你决定，框架就没机会把它藏起来。默认重试最坏的形态是静默重试 —— 调用方以为只发了一次，实际发了三次，还查不出来。
2. 2留一个打开原始报文的开关，生产环境默认关闭、按会话临时打开。框架自带的日志格式一旦和你的 trace 体系对不上，这个开关就是你唯一还能自己控制的排障入口。

连同那份清单一起，这一层通常也不超过两百行。它们不解决任何业务问题，但决定了出事那天你是十分钟定位还是一下午定位，而出事这件事是一定会发生的。