架构与系统设计 / 系统课时
给事件定义稳定的消息信封
给事件定义稳定的消息信封
同一条订单事件经过重试、转发和多个消费者后,仍应能回答“发生了什么、来自哪里、是否重复、属于哪次业务流程”。本篇用稳定信封分离通用元数据与业务载荷,并通过本地示例验证重发时身份不变。
学习目标
- 区分事件身份、发生时间、业务关联标识和直接前因。
- 定义可复用的信封,明确标准字段与自定义扩展。
- 生成订单事件,验证重发不改变身份和发生时间。
信封负责识别,载荷负责解释
本篇把通用信息放在信封,把订单号、金额等业务事实放入 data。这样,通用入口可以按 type 分派处理器,日志可以关联业务流程,订单处理器才需要理解金额字段;增加消费者不必重新发明一套消息外壳。
采用 CloudEvents 1.0.2 规范作为基线,消息中的 specversion 仍写 1.0,它不是业务版本。标准必填属性只有 id、source、specversion、type;团队可以另外要求提供发生时间和业务载荷。([GitHub][1])

不要让三个标识互相代替
先区分事件自身、整段业务流程和直接前因。本篇为它们约定不同的标识,不能因为三个值都长得像 UUID,就把它们当作同一种字段。
| 字段 | 标识什么 | 本篇约定 |
|---|---|---|
id |
一次具体事件 | 同一事件重发保留,新事件重新生成 |
correlationid |
一次业务流程 | 同一流程中的多条事件共享 |
causationid |
直接触发者 | 指向产生本事件的命令或上游事件 |
correlationid、causationid 是本篇自定义扩展,不是 CloudEvents 核心属性。扩展属性名使用小写字母和数字。本例约定命令 ID 全局唯一;若上游事件 ID 只在来源内唯一,应再携带来源,不能只靠前因 ID 定位。([GitHub][1])
CloudEvents 用 source 与 id 的组合识别事件。本篇要求 source 使用稳定的逻辑来源,而非易变的实例 IP;time 记录业务发生时间并携带时区,重发时不覆盖成当前时间。规范中的 time 采用 RFC 3339 格式。([GitHub][1])
type 表达已经发生的事实,例如 com.example.order.confirmed.v1,后缀是本篇业务主版本约定;不要用它保存处理器类名。data 则明确业务单位:本例 totalAmountMinor 是整数分,currency 为 CNY,12900 表示 129 元人民币。
生成一份可重发的订单事件
以下程序使用 Python 标准库,可在 Python 3.10 及以上运行。保存为 envelope_demo.py,执行 python envelope_demo.py。它只模拟序列化与重试读回,不连接消息系统,也没有真正落盘。
import json
from datetime import datetime, timezone
from uuid import uuid4
def main():
# 模拟订单此刻确认;生产中应使用业务记录的发生时间。
occurred_at = datetime.now(timezone.utc).isoformat()
event = {
"specversion": "1.0",
"id": str(uuid4()),
"type": "com.example.order.confirmed.v1",
"source": "urn:example:service:orders",
"time": occurred_at,
"datacontenttype": "application/json",
"correlationid": str(uuid4()),
"causationid": str(uuid4()),
"data": {
"orderId": "order-demo",
"totalAmountMinor": 12900,
"currency": "CNY"
}
}
# 用序列化结果模拟待发送记录,重试复用原记录。
wire = json.dumps(event, ensure_ascii=False)
resent = json.loads(wire)
# 检查身份与发生时间,不能在重试时重新生成。
original_key = (event["source"], event["id"])
retry_key = (resent["source"], resent["id"])
assert original_key == retry_key
assert event["time"] == resent["time"]
print(json.dumps(resent, ensure_ascii=False, indent=2))
print("身份与发生时间保持不变")
if __name__ == "__main__":
main()预期输出:
{
"specversion": "1.0",
"id": "<ID>",
"type": "com.example.order.confirmed.v1",
"source": "urn:example:service:orders",
"time": "<TIME>",
"datacontenttype": "application/json",
"correlationid": "<ID>",
"causationid": "<ID>",
"data": {
"orderId": "order-demo",
"totalAmountMinor": 12900,
"currency": "CNY"
}
}
身份与发生时间保持不变三处 <ID> 分别代表事件、业务流程和前因的不同 UUID;<TIME> 是实际运行时带时区的时间,值每次运行可能不同。order-demo 是固定测试订单号。程序把本次确认视为此刻发生,而不是建议生产端用发送时间替代业务时间。
生产环境应从入口上下文传入流程标识和前因标识,不能像演示那样在每个服务随机重建。序列化后的同一条记录可以被重发;后续产生“库存已预留”等新事件时,则需要新的事件身份。
把契约变成发布前检查
除了字段名,还要记录类型、必填性、缺失含义和负责维护的团队。发布前检查必填属性非空、时间可解析,再按事件类型验证载荷;金额不能变成字符串,币种也不能靠消费者猜测。
建议将事件身份、发生时间与载荷一同持久化,重试读取原记录。可把“订单确认”和“订单取消”各生成一次,再检查它们是否拥有不同事件 ID;二者即使属于同一个订单,也不是重复事件。
稳定信封的关键不是字段越多越好,而是通用字段含义固定、业务载荷边界清楚,并且重试不会把同一事实伪装成另一条新事件。