架构与系统设计 / 系统课时
设计异步事件的契约边界
设计异步事件的契约边界
异步集成的难点不是把消息发送出去,而是决定什么事实值得长期成为跨服务契约。本篇通过订单完成事件说明如何区分领域事件与集成事件、过滤内部模型细节,并让发布者和消费者能够独立演进。
学习目标
- 区分服务内部领域事件与跨服务集成事件的职责
- 围绕已经发生的稳定业务事实设计事件名称和载荷
- 避免消费者依赖发布者的聚合结构、内部枚举和持久化字段
领域事件不等于集成事件
领域事件首先服务于当前限界上下文,例如订单聚合内部可能产生 OrderPaymentConfirmed,供本服务更新状态、计算履约条件或触发本地规则。它可以包含当前模型需要的信息,也可以随着领域模型一起重构。
跨服务事件则是对外承诺。发布者必须明确哪些业务事实允许其他上下文依赖,并把内部事件转换成独立的集成契约。例如订单服务内部经历多个状态后,对外只公布稳定事实 OrderConfirmed,下游无需知道确认过程由哪些内部对象协作完成。

用已经发生的业务事实命名
集成事件应描述已经成立的业务事实,而不是向其他服务下命令。OrderConfirmed 表示“订单已经确认”,消费者可以自行决定是否预留库存、创建履约任务或更新分析数据。相比之下,ReserveInventoryNow 把发布者对消费者行为的期待写进了消息,会削弱消费者自治。
事件名称还应避免携带实现细节。诸如 OrderRowInserted、OrderAggregateSaved 描述的是数据库或代码行为,不代表其他上下文真正关心的业务变化。只有当一个事实对边界之外具有稳定业务意义时,才值得成为集成事件。
为消费者设计最小事件载荷
事件载荷应让消费者理解这个事实,同时避免复制整个聚合。下面是一个集成事件的数据结构示例;它描述契约,不是可以单独运行的程序。
{
"eventId": "<ID>",
"eventType": "OrderConfirmed",
"occurredAt": "<TIME>",
"orderId": "<ID>",
"customerId": "<ID>",
"items": [
{
"sku": "SKU-1001",
"quantity": 2
}
]
}eventId 用于识别一次事件,occurredAt 表示业务事实发生时间,实际值会随运行而变化。载荷提供订单标识、客户标识以及下游确实需要的商品和数量,却没有传播订单聚合中的付款对象、内部状态机节点、ORM 字段或领域服务结果。
验证事件契约时,应使用 JSON Schema、AsyncAPI 或等价的契约测试检查必需字段、类型和兼容性,并让消费者测试基于公开字段执行,而不是反序列化发布者的内部类。
在发布前完成模型转换
比较安全的边界做法是:领域模型先产生内部事件,应用层或专门的映射器再决定是否生成集成事件。这样,内部领域语言可以持续演进,对外契约则由独立的发布策略管理。
如果直接序列化领域事件,发布者会很快失去重构自由。例如把订单中的 payment 对象拆成多次支付记录,本来只是订单上下文内部重构;一旦整个对象曾经被发给消费者,这次修改就可能演变成跨团队迁移。
让事件契约独立演进
事件一旦进入消息系统,就可能被多个未知消费者长期保存和重放,因此删除字段、修改字段含义或改变枚举语义都比进程内重构危险。优先采用新增可选字段等兼容变化,并让消费者忽略自己不认识的附加字段。
设计完成后,可以用一个简单标准检查边界:消费者只看到公开事件时,是否能够理解发生了什么,并完成自己的决策;同时发布者替换内部聚合结构时,是否无需通知所有消费者。如果两点都成立,这个事件才真正承担了上下文之间的契约,而不是成为内部对象的远程副本。