企业微信事件驱动架构怎么设计

别把平台事件直接当领域事件用

回调推过来的是「平台侧发生了什么」，业务关心的是「这对我们意味着什么」。两者看起来常常一一对应，于是最省事的做法是把回调报文透传给业务处理器。这笔账会在两个时刻结算：平台侧的事件结构调整时，以及你要接入第二个消息来源时。

中间那层不用做得多重，它只干三件事：把报文翻译成自己定义的领域事件、补齐业务标识（把平台侧的会话与人员标识映射成自有系统的 ID）、丢掉业务不关心的字段。翻译完之后，业务代码只认自己的事件类型，平台侧怎么变都由这一层吸收。

// 示意逻辑，事件类型与取值方式以 wecomapi 文档为准
// 平台侧字段一律通过取值函数读，要改只改这一个文件
function toDomainEvent(raw) {
  const kind = platformKindOf(raw);
  return {
    id:         newId(),                       // 自己生成，与平台标识分开
    type:       DOMAIN_TYPE[kind],             // 平台类型 → 业务语义
    version:    1,                             // 契约版本，第一版就加上
    accountId:  accountOf(raw),                // 来源账号
    subject:    mapContactId(subjectOf(raw)),  // 平台标识 → 自有系统 ID
    occurredAt: producedAtOf(raw),
    payload:    project(raw, KEEP[kind]),      // 只保留业务用得上的部分
  };
}

• 领域事件按业务语义命名（客户已接入、会话已转接、群成员已退出），不要照抄平台事件类型名。
• 每个领域事件带自己生成的事件标识、来源标识（哪个账号、哪次投递）和产生时刻。
• 翻译层不做业务判断。它只负责说清「发生了什么」，不负责决定「该做什么」。

事件里带多少数据：通知型还是快照型

第二个决定是事件里塞什么。一端是通知型 —— 只说「某某会话有变化」，消费者拿到之后自己回查详情；另一端是快照型 —— 把变化后的关键状态放进事件里，消费者不用再问。

通知型的好处是事件小、契约稳，多一个字段也不用惊动下游；代价是每条事件换来一次回查，量大时回查本身就会撞上频率约束。更隐蔽的代价是时间错位：回查拿到的是「现在」的状态，不是事件发生那一刻的状态。同一个对象连续变更两次，两个消费者可能都读到第二次的结果，中间那个状态永远丢了。

快照型反过来：消费者自给自足、可以离线重算，但事件变大、契约变紧，任何字段调整都会波及所有订阅方。

实践里的分法是按事件性质来，不是按团队偏好来：状态类事件带快照，动作类事件用通知。群成员变更、客户属性变更这种「结果重要、过程不重要」的，把变更后的关键字段带上；消息、申请这种「每一条都独立且本身就是全部信息」的，既不需要回查也不需要快照。

落地时把两类分开建模：用 wecomapi 的事件回调拿到原始投递之后，翻译层按类型决定要不要补一次查询，补完再往下发。这次补查询只在翻译层做一遍 —— 让每个消费者各查各的，五个消费者就是五倍请求量，而且它们还会拿到互不一致的结果。

消费者按业务能力切，不按事件类型切

常见做法是一个事件类型对应一个处理函数。规模小的时候没问题，涨到十几个类型、每个类型要做三四件事之后，处理函数就变成大杂烩：一个函数里同时写会话库更新、CRM 推送、机器人回复和指标打点，任何一件失败都要决定整个函数要不要重试 —— 而正确答案往往是「只重试其中一件」，这在单函数结构里表达不出来。

更耐用的切法是按业务能力划消费者：会话同步、客户档案、自动应答、数据回流各是一个独立消费者，各自订阅它关心的那几类事件（多对多关系），各自维护消费位点、重试策略和幂等记录。一个消费者挂了，其他的照跑。这和站内讲队列时说的「按事件类型分消费组」不冲突：那一层分的是快慢与故障隔离，这一层划的是逻辑归属，同一个消费者可以横跨几类事件。

• 一个消费者只对一件事负责，失败语义因此变得清晰：这件事没做成，只重试这一件。
• 消费者之间不互相调用。要串起来就发一条新的领域事件，别在消费者里直接调另一个消费者的函数。
• 慢消费者（要调模型、要下载文件）单独一组，别和毫秒级的状态更新抢同一份并发度。
• 幂等记录的键必须带上消费者身份，这是按能力切分后立刻会踩到的第一个坑；键该怎么取、去重窗口怎么定，站内讲回调幂等的那篇有专门一节。

订阅关系要落在自己的配置里：每个消费者声明它关心哪几类领域事件，事件订阅只负责把投递送到入口，分发给谁由你的路由表决定。把路由写死在代码的 switch 里，加一个消费者就得改一次分发逻辑，这条路走不远。至于队列本身怎么分区、死信怎么处置，站内另有一篇专讲，这里不重复。

这样切之后，加需求的成本变成常数：新增一个业务能力就是新增一个消费者，不用动任何现有代码。这是事件驱动相比直接调用最实在的那点收益，也是唯一值得为它付出复杂度的理由。如果你确定订阅方永远只有一个，这层复杂度就不值。

事件契约怎么演进

事件驱动系统里最贵的变更不是加功能，是改事件。一个事件被五个消费者订阅，改一个字段就要协调五次发布，而且这五次不可能同时到达。所以契约演进的全部技巧，都是为了让新旧版本能共存一段时间。

1. 1只增不改不删：新增字段一律可选，老字段哪怕废弃了也先留着，等确认没人读了再摘。
2. 2版本号放在事件体里，不要放在 topic 名里。放 topic 名会让每次升版都要改订阅关系，等于把成本转嫁给所有消费者。
3. 3消费者解析时必须对未知字段宽容。用严格模式反序列化，生产者一加字段消费者就集体报错，这类事故的排查时间通常远长于修复时间。
4. 4破坏性变更走并行发布：新旧两个事件同时发一段时间，消费者逐个迁移，全部迁完再停旧的。

重放：先想清楚在重放什么

「能重放」是事件驱动最常被拿出来说的能力，也是最常做错的。做错的根源在于没区分三种重放 —— 它们的目标、投递范围和安全边界完全不同。

1. 1修复型：代码有 bug，把一段时间的事件重新过一遍，把内部状态修对。必须屏蔽全部外发动作，否则客户会重新收到一遍昨天的话术。
2. 2补建型：新上线一个消费者，需要用历史事件给它建初始状态。只能投给这一个消费者，不能广播 —— 广播等于让所有老消费者把历史又执行一遍。
3. 3分析型：把历史事件导到离线环境算指标、验证新规则。这一种最安全，也最该做成常态能力，它能让「改规则前先跑一遍历史数据」变成日常操作。

三种都依赖同一个前提：原始投递报文和翻译后的领域事件都要留档，而且要分开留两份。只留领域事件，翻译逻辑本身的 bug 就永远修不回来；只留原始报文，重放时必须重跑整条翻译链，而历史报文遇到新版翻译代码可能直接解析失败。两份的存储成本远低于任何一次「数据修不回来」。

具体做法：在 wecomapi 的回调入口完成验签之后、翻译之前，先把原始字节按天归档；翻译产出的领域事件另存一份带版本号的日志。重放接口按「时间范围 + 事件类型 + 目标消费者 + 是否允许外发」四个参数发起，其中「是否允许外发」默认关闭，要真发出去必须显式打开。

• 重放请求本身也要留痕：谁在什么时候重放了哪一段。复盘时这条记录比翻日志有用得多。
• 重放走独立的消费组或通道，不要挤实时流量的位点，否则一次补数会把当天的时效指标全打坏。
• 给单次重放设总量上限。手滑把半年的事件一次性灌进去，比原来的 bug 严重得多。

最后一句判断：事件驱动不是免费的。多一层翻译、多一份契约维护、多一套归档与重放，排障时链路也从一跳变成三跳。只有一个消费者、而且短期内看不到第二个的时候，直接在回调里调业务函数是更诚实的选择。该不该上，看的是「订阅方会不会增长」，不是事件量大不大。