架构与系统设计 / 系统课时

给事件定义稳定的消息信封

给事件定义稳定的消息信封

同一条订单事件经过重试、转发和多个消费者后,仍应能回答“发生了什么、来自哪里、是否重复、属于哪次业务流程”。本篇用稳定信封分离通用元数据与业务载荷,并通过本地示例验证重发时身份不变。

学习目标

  • 区分事件身份、发生时间、业务关联标识和直接前因。
  • 定义可复用的信封,明确标准字段与自定义扩展。
  • 生成订单事件,验证重发不改变身份和发生时间。

信封负责识别,载荷负责解释

本篇把通用信息放在信封,把订单号、金额等业务事实放入 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。它只模拟序列化与重试读回,不连接消息系统,也没有真正落盘。

python
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()

预期输出:

text
{
  "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;二者即使属于同一个订单,也不是重复事件。

稳定信封的关键不是字段越多越好,而是通用字段含义固定、业务载荷边界清楚,并且重试不会把同一事实伪装成另一条新事件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给事件定义稳定的消息信封

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通