企微外部群开发怎么落地

建群不是一次调用，是一个作业

大多数人的第一版是这么写的：业务请求进来，同步调 wecomapi 的建群接口，拿到群标识写库，返回成功。这一版在演示环境永远能跑通，在生产上会从两个地方裂开。

一是建群返回和群真正可用之间存在时间差。返回成功只说明请求被受理，群的初始化、群主身份生效、可被邀请的状态未必在同一瞬间完成。紧接着就拉人，就有一定概率打在还没准备好的群上，而且这种失败往往不是稳定复现的，排查起来最费时间。

二是重试。业务请求超时了，前端点第二次，或者你的任务框架自动重试 —— 如果没有幂等键，你会拿到两个群。失败的群可以重建，重复的群很难清理：人已经进去了，撤销的成本最后落在运营身上。

1. 1把建群做成异步作业。业务侧只拿到一个作业标识，群标识由作业完成后回写，不要让业务请求同步等在建群上。
2. 2幂等键由业务侧生成，比如「活动标识 + 批次号 + 序号」的组合，随请求带上，重试时用同一个键。生成规则要能从业务数据里重算出来，而不是随机数。
3. 3给群维护一个自己的状态机：creating → created → ready → archived。ready 由后续的可用性确认或第一个群事件推进，只有 ready 的群才允许进入拉人和群发队列。

拉人：以事件为准，不以返回为准

邀请入群是一个请求，不是一个结果。接口返回成功，意味着邀请已经发出，不代表对方已经在群里 —— 对方可能没点、可能过期、也可能进来又退了。

第一版系统最常见的错误就是用调用返回记账：调成功就把这个人写成「已入群」。跑一周之后，你库里的群成员和真实群成员开始分叉，而且是单向分叉，只多不少。等到要做「按群成员分层触达」的时候，这批脏数据会直接变成打给不存在成员的消息，再往后就是运营拿着两份对不上的名单来找你。

正确的分工其实很简单：调 wecomapi 的邀请接口只写「已发起邀请」这个事实，成员关系一律由入群/退群事件回调写入。两张表，两个来源，不要混。

• 邀请记录表：谁、什么时候、往哪个群、发起结果如何、是否已被事件闭合。
• 成员关系表：只接受事件驱动的写入，业务代码一律不许直接改这张表。
• 超过时间窗仍未被事件闭合的邀请记为失效，进入重触或放弃流程，而不是永远挂着占位。

这套结构还有个附带好处：入群率变成可以直接算出来的指标（被事件闭合的邀请数 / 发起的邀请数），不需要另做一套埋点。邀请文案改版有没有效果，看这个比值就够了。

群档案：事件增量为主，对账为辅

群名、公告、成员数、标签这类群信息是典型的会腐化的数据。维护方式无非两种：定时全量拉取，或者事件增量更新。绝大多数团队默认选了前者，因为写起来最省事。

全量拉取的问题不是慢，是调用量随群数量线性增长。群到了几千个，一次全量就是几千次调用，你的频控预算会被对账本身吃光，真正要紧的业务触达反而被挤到后面排队。这是外部群规模化之后第一个撞墙的地方。

建议的分工是：事件增量做实时，低频全量做对账。事件负责让数据「大致正确且及时」，对账负责在固定窗口把漏掉的差异补回来。对账不追求实时，所以它可以放在业务低峰、可以只抽样、可以按「最后对账时间」排序优先处理最旧的那一批，还可以在频控吃紧时整体让路。

群档案的最小字段集里有一列特别容易被漏掉：这个群归属哪个账号在管。单账号阶段这一列显得多余，多账号一上来就是刚需 —— 群发要按账号排队、频控要按账号计算、某个账号异常时要立刻找出受影响的群，全都依赖它。事后补这一列的代价是全表回填加一轮业务代码改造，一开始就加上几乎不花钱。

分层群发：限速要限在账号上

群发的第一版通常是遍历群列表逐个发。这一版能跑，但里面有两个隐含假设是错的：一是假设所有群该收到一样的内容，二是假设限速可以按任务来做。

第一个假设的代价是打开率和退群率。分层的最小可用做法不需要复杂标签体系：按群的来源（哪个活动或渠道建的）、活跃度（最近有没有互动）、阶段（新群还是成熟群）三个维度分桶，能分出三到五个桶就足以拉开差距，再细下去的边际收益远不如把内容改好。

第二个假设的代价更贵。频控是账号级的资源，不是任务级的。当你有三个群发任务同时在跑、恰好都用同一个账号，每个任务各自限速到自认为安全的值，合起来就是三倍。任务越多撞得越狠，而且这个问题在测试环境永远复现不出来 —— 测试的时候只有一个任务。

所以正确的结构是把决策和投递拆开：任务只负责决定「发什么、发给哪些群」，调度器负责决定「什么时候真的发出去」。中间用一个账号维度的队列隔开，所有任务的投递项都进这个队列，出队速率由账号级的令牌桶控制。

// 示意逻辑，表达的是限速粒度 —— 每个账号一个桶，而不是每个任务一个桶
const buckets = new Map(); // accountId -> 令牌桶

async function dispatch(item) {
  const bucket = buckets.get(item.accountId);
  await bucket.take();                 // 拿不到令牌就等，不要丢弃投递项
  try {
    await sendToGroup(item);             // POST https://manager.wecomapi.com/message/sendText
    bucket.onSuccess();                // 连续平稳时缓慢提速
  } catch (e) {
    if (isRateLimited(e)) {
      bucket.onThrottled();            // 命中频控立刻大幅降速
      await requeueWithBackoff(item);  // 退避重排，间隔带随机抖动
    } else {
      await deadLetter(item, e);       // 参数/权限类失败重试无意义
    }
  }
}

令牌桶的速率不要写成常量。合理的做法是给一个保守的初始值，成功时缓慢上调、命中频控时立刻大幅下调，让系统自己收敛到当前实际可用的速率。写死常量的问题在于它永远是错的：设高了伤账号，设低了任务跑不完，而正确值会随时间、账号状态和平台策略变化。

落地顺序

1. 1先把一个群从建到 ready 完整跑通，包含幂等键与状态机，全程只用一个账号。
2. 2接上入群/退群事件，让成员关系完全由事件写入，跑够一周再看数据是否自洽。
3. 3加对账作业，观察它每天补回多少差异 —— 这个数字直接反映事件链路的健康度，比任何监控指标都诚实。
4. 4最后做群发，从单账号单任务开始，确认队列与限速真的生效之后，再加账号、加任务。