企业微信 SDK 怎么选

「SDK」这个词底下压着三种东西

同样一句「要不要用企业微信SDK」，问的人心里可能是三件完全不同的事：平台方给的语言包、社区维护的开源库、你自己封的那层内部客户端。这三类分别意味着什么、以及「库」和「框架」的界线在哪，站内讲协议 SDK 与开发框架那篇已经拆过一遍，这里不再重复分类，直接说怎么选。

所以这个问题的正确问法不是「用不用 SDK」，而是「鉴权、超时、重试、错误分类、日志这几件横切逻辑，分别写在几个地方」。如果答案是一个地方，你已经有一层封装了，它叫什么名字不重要；如果答案是五个地方，那你现在就该动手，跟用不用现成的库也没关系。

直接发 HTTP 什么时候就是对的

以 REST 为主的接口 —— HTTPS、Bearer 鉴权、JSON 收发 —— 任何语言的标准库都能调。项目里只有三五个调用点、只有一种语言、这段逻辑一年也不会动，那就直接发 HTTP，多一层封装是纯负债：你要为它写文档、写测试、处理版本，而它替你省下的只有几行样板。

翻转点不在接口数量上，在横切逻辑被复制的次数上。面对 wecomapi 这种统一 Bearer 鉴权、统一错误模型的接口，每件横切逻辑单看都很薄 —— 设个超时、带个 header、判一下要不要重试。薄到你会低估它被复制到第五个调用点之后的样子：那时候改一个超时值要改五处，而你只会记得改三处，剩下两处会在半夜以「某个后台任务一直挂着」的形式提醒你。

• 同一段「取凭证 → 带 header → 判响应 → 决定重不重试」出现在三个以上文件里。
• 开始有人在业务代码里写 catch 之后原地 sleep 一下再试一次。
• 线上出问题时，你没法从日志里还原出「当时到底发了什么、对面回了什么」。

这三条命中任意一条，就该封了。命中两条以上还在拖，后面付的不是封装成本，是排障成本 —— 后者不封顶。

用现成的库，三笔成本要先算

现成的库省的是启动时间，花的是控制权。三笔成本按出现顺序排：

1. 1版本滞后。库的更新永远晚于接口，而你需要的那个新能力往往正好落在滞后区间里。到时候你要么等，要么在库外面再发一次裸请求 —— 于是同一个项目里出现两种调用风格，日志格式、错误处理、重试策略全都对不上。
2. 2覆盖不全。作者当初只需要发消息，那客户与群这块大概率是空的。补是能补，但你补的代码要跟着上游的抽象走，改起来比自己写一遍还别扭。
3. 3异常语义被吞。这是最贵的一笔：库把结构化的错误响应包成一个通用异常，只留一句 message。你失去的不是可读性，是「这个错误该不该重试」的判断依据，而这个判断是整套重试与告警策略的地基。

自己封一层：该封的五样，不该封的三样

封装层的价值全部来自「只有一份实现」。所以判断一样东西该不该进这层，只看它是不是在每个调用点都要重复一遍。该进的有五样：

1. 1凭证的获取与刷新。调用方不该看见 token 这个词，更不该各自缓存一份。
2. 2错误分类。把响应翻译成你自己的三档：可重试、不可重试、需要人工。重试、告警、降级三套逻辑共用这一个输入，它只能有一份实现。
3. 3出向限速与退避。放进这层，业务代码就不需要知道速率这件事存在。
4. 4幂等键的透传。键由业务侧生成（它才知道这个动作的自然唯一性），封装层只负责带上并在重试期间保持不变。
5. 5请求留痕。每次调用带一个可追溯的标识，把请求、响应、耗时记成一条结构化日志。这条是前面四条出问题时唯一的线索。

• 不该封业务编排。「新客户通过之后发欢迎语再打标签」是业务流程，塞进封装层，这层很快会长出一堆只有一个调用方的方法。
• 不该建全量 DTO。给每个响应做字段齐全的映射，对端加一个字段你就得跟着发版。只映射你真的要用的字段，原始响应留一份。
• 不该追求全接口覆盖。只封你在调的。为「以后可能用到」提前封的方法，八成到废弃那天都没被调用过一次。

// 示意逻辑，精确字段名、错误分类与端点以线上接口文档为准
async function call(path, body) {
  const traceId = newTraceId();
  const started = Date.now();

  const res = await fetch(`https://manager.wecomapi.com${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${await token.get()}`, // 凭证：调用方看不见
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(5_000),             // 超时：只在这里定
  });

  const raw = await res.json();        // 原始响应留着，不做全量映射
  log({ traceId, path, ms: Date.now() - started, raw });

  if (!isOk(res, raw)) throw classify(res, raw);    // 分类只写这一处
  return raw;
}

// 业务动作只是一层命名，不是又一套抽象
export const sendText = (guid, toId, content) =>
  call("/message/sendText", { guid, toId, content });

还有一条容易被忽略的设计要求：封装层必须能被绕过。留一个能发原始请求的出口，让业务方在遇到这层还没覆盖的能力时能自己接一下，而不是被迫等你发版。没有这个出口的封装层，最后都会被人在旁边偷偷重写一个，然后你就有两层了。

按团队规模，判断线在这三档

团队形态          一两个人 · 单语言    3-8 人 · 一到两种语言   多团队 · 三种以上语言
----------------  -------------------  ----------------------  ----------------------
建议形态          裸 HTTP + 几个函数   一个内部客户端模块      带版本号的内部包
封装的边界        超时 + 错误判断      上面那五样横切逻辑      五样 + 跨语言一致的约定
最大的风险        基本没有             长成第二个业务层        各语言实现悄悄跑偏
谁来维护          写的人               有明确 owner            要有评审和废弃流程
什么时候该升档    调用点过十个         第二种语言出现          第三种语言出现

两个升档时机比档位本身更值得记。第一个：当你发现第二个调用点是复制第一个的错误处理来的，就从裸 HTTP 升到内部模块 —— 这时候动手是二十行的事。第二个：当第二种语言出现，就把错误分类和重试策略从代码里抽成一份语言无关的约定表。

多语言那一档真正贵的不是写四遍代码，是让四种语言对同一个错误做出同样的反应。可行的做法是先写那份约定表 —— 哪些响应算可重试、退避怎么走、幂等键由谁生成、日志字段叫什么 —— 再让各语言照着实现，而不是让四个作者各自去读一遍 wecomapi 的错误约定、各自理解一遍。跑偏的成本不会在写的时候暴露，会在某次故障里，以「同一个错误，Java 侧重试了 Python 侧没有」的形式暴露。

让这层不腐烂的三条规矩

1. 1内部包也要有版本号和废弃期。没有版本号的共享代码，改一行就要问遍所有调用方，问到第三次就没人敢改了。
2. 2不给封装层加业务开关。第一个 options.skipRetry 是参数爆炸的起点，半年后这层会有十二个开关，其中十个只有一个调用方用过一次。
3. 3每季度删一次没人调的方法。如果删不掉的原因是「不知道谁在调」，那说明请求留痕那条没做好，先补它。