企业微信开发怎么做：架构、队列与上线清单

企业微信开发容易做成「把官方文档接口逐个调一遍」。真正能上线的项目，是先定消息落点，再定架构，最后才写调用。这篇按工程顺序写：目录怎么拆、队列怎么做、上线前过什么。

开发目标先缩小

一次只做一个落点。推荐的最小目标：

• 某个企业微信账号保持在线可观测

• 业务系统能向 一个测试外部群 发文本

• 每条发送有 requestId、有终态

• 掉线时出站停止

先不要做：全量通讯录同步、自动建群拉人、群内 AI 自动回复、多组织权限中心。那些是另一条产品线。企业微信开发里范围失控，比技术选型错误更常见。

架构按四层拆，避免业务代码操作窗口

业务层    订单 / 课次 / 社群运营（决定发不发、发给谁）
编排层    任务、审核、窗口、限速、幂等
通道层    官方应用消息  或  外部群会话（RPA/二次封装 HTTP）
实例层    企业微信客户端在线、登录、掉线恢复

硬规则：

• 业务层禁止出现群名、窗口标题、点击步骤

• 编排层禁止在通道超时后换一个新单号重发

• 实例层挂了，编排层必须切断该实例队列

官方能力和二次开发能力在通道层分两个 adapter。函数名都叫 send，内部配置、错误码、重试策略都不要共用。

数据表最小集

没有这四张表，代码会把状态散落在日志里：

account_instance

实例 ID、企微账号标识、在线状态、最后心跳。

group_map

业务群 ID、外部群 ID、绑定实例、状态（正常 / 退群 / 禁用）。

send_task

request_id、业务单号、实例、目标、payload 摘要、状态机、下次可发时间。

send_event

回执原始分类、时间、操作者（若人工触发）。

状态机建议只留：pending → sending → success / failed / cancelled。不要发明十几个中间态却没有人处理。

队列是开发的核心，不是附属

业务事件进来先落 send_task，再入队。消费时：

1. 抢锁（按实例维度串行或限速）

2. 检查窗口、频次、映射有效

3. 调通道

4. 写 sending

5. 等回执落地终态

同一实例不要用无限并发打发送。企业微信开发在外部群场景，吞吐瓶颈在账号行为，不在你的 CPU。

延迟任务用「下次可发时间」扫描或延迟队列，不要 sleep 在请求线程里。夜间窗口、限频后退避，都走这个字段。

通道适配：官方和外部群分开写

官方应用消息适配器

适合员工。关注 agentid、touser、出错码官方语义。

外部群会话适配器

适合客户群。关注实例在线、群 ID、异步回执。底层无论是自研 RPA 还是现成 HTTP，对编排层暴露的方法应一致：

online(instanceId)
sendText(instanceId, groupId, text, requestId)
sendMedia(...)
getResult(requestId)

企业微信开发最省事的错法，是在 Controller 里直接 if-else 两套完全不同的参数。三个月后没人敢改。

本地开发和联调怎么做

• 永远先打测试号、测试群。生产映射表默认关闭发送开关。

• 用固定 request_id 的脚本测幂等，不要每次手工点。

• 模拟三种故障：进程杀掉（离线）、映射改成错误群 ID、通道超时。

• 日志默认打 ID 和状态，不打完整客户文案。

没有故障演练的企业微信开发，上线第一周就会在真实客户群里练。

上线清单

代码合并前逐项打勾：

1. 测试群文本成功，回执成功

2. 同一 request_id 重复提交，群内一条

3. 实例离线，任务停在 pending/failed，无假成功

4. 账号不在群，失败原因可给运营看

5. 群名修改，映射仍命中原群 ID

6. 发送接口需鉴权，内网裸调用被拒绝

7. 生产开关默认关，审核或白名单才放行

8. 监控：在线、成功率、堆积、失败分类

缺第 2、3、6 条，不要标「已完成企业微信开发」。

迭代顺序

一期 单实例单群文本 + 四张表 + 队列。

二期 映射管理后台、窗口与限速、失败分类展示。

三期 图片文件、多实例、人工审核后的多群任务。

活动全量不是功能，是战役：名单、文案、窗口都要另开审核流。不要写进一期的默认消费者里。

小结

企业微信开发怎么做，关键是缩小落点、四层架构、任务表驱动、官方与外部群通道隔离。先让一条测试群消息可对账，再扩规模。队列、幂等、掉线停发比多接几个官方模块更决定能不能上生产。开发完成的标志是故障可解释、重复可拦截、生产默认安全，而不是接口清单被勾满。