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

定义订单域的事件契约

定义订单域的事件契约

订单消息能被发送,不代表消费者能正确理解。本篇以订单确认事件为主例,明确生命周期中的事实、载荷边界、事件身份、版本和因果关系,并用可运行校验检查金额与订单标识,形成可供生产者和消费者共同遵守的契约。

学习目标

  • 根据已经发生的订单事实命名事件,划清订单域与其他业务域的发布边界。
  • 区分事件标识、订单标识、关联标识以及三种不同的版本含义。
  • 编写事件样例,并验证业务约束与契约升级的兼容边界。

从已提交的业务事实命名

本例约定,订单域发布下面四类事件。每种载荷都包含非空字符串 orderId 和正整数 aggregateVersion;其余字段只表达该事实所需的信息,不直接复制整张订单表。

事件名称 成立条件 额外业务字段
OrderCreated 订单和初始明细创建成功 customerId、items
OrderConfirmed 订单确认规则通过 确认时的客户、金额、币种和明细快照
OrderCancelled 取消规则通过,订单正式取消 reasonCode
OrderCompleted 订单域确认履约已经完成 fulfillmentId

这里的“已确认”不等于“支付成功”,取消订单也不等于退款完成。ConfirmOrder 是请求执行动作的命令;PaymentCaptured、StockReserved 应由掌握相应事实的支付域、库存域发布,不能由订单服务猜测生成。

只在业务事务成功后让事件对外可见。落地时,可将订单变更与待发送事件写入同一个事务中的 Outbox 表,再由发布器投递;事务回滚时不应留下可发送的成功事件。([AWS 文档][1])

固定确认事件的信封和快照

采用 CloudEvents 1.0 信封承载事件身份和类型,把业务快照放入 data。correlationid、causationid 是本项目自定义的扩展属性,不是 CloudEvents 的必填标准字段;本项目要求主示例中的字段全部存在。([GitHub][2])

以下是完整消息结构样例。各类 <ID> 分别替换为实际标识,subject 与 data.orderId 必须相等;<TIME> 替换为 RFC 3339 格式的 UTC 事实发生时间,不能原样发送。CloudEvents 对存在的 time 属性要求使用 RFC 3339。([GitHub][3])

json
{
  "specversion": "1.0",
  "id": "evt-order-<ID>",
  "source": "urn:example:order-service",
  "type": "com.example.order.OrderConfirmed.v1",
  "subject": "order-<ID>",
  "time": "<TIME>",
  "datacontenttype": "application/json",
  "correlationid": "flow-<ID>",
  "causationid": "cmd-<ID>",
  "data": {
    "orderId": "order-<ID>",
    "aggregateVersion": 2,
    "customerId": "customer-<ID>",
    "currency": "CNY",
    "totalAmountMinor": 12900,
    "items": [
      {
        "skuId": "sku-<ID>",
        "quantity": 2,
        "unitPriceMinor": 6450
      }
    ]
  }
}

预期结果:消费者从快照即可得知,订单确认时包含两件单价 6450 分的商品,合计 12900 分,不必回查订单服务才能还原这次确认的金额。这是事实发生时的快照,不是订单当前状态的查询响应。

本例限定币种为 CNY,金额用非负整数表示“分”,数量必须为正整数,明细不能为空,业务标识必须为非空字符串。示例不含运费和折扣,因此总额等于明细小计之和;引入优惠后应先定义新的金额组成,不能继续套用旧等式。

让身份、因果关系和版本各司其职

CloudEvents 使用 source 与 id 的组合识别事件。本项目规定,重投同一事实时保留这两个值以及原始时间和载荷;消费者按“逻辑订阅名称、事件来源、事件标识”建立幂等键,而不是只按订单号去重。([GitHub][2])

correlationid 表示一次业务流程,全链路沿用;causationid 指向直接导致当前事件的命令或事件。本项目进一步要求命令和事件的标识全局唯一,避免跨服务引用时含义不明;这些关联标识不承担消息去重职责。

同一订单流程中的事件身份与直接因果关系

三个版本也不能混用:specversion 描述 CloudEvents 信封规范;类型末尾的 v1 是本项目的业务契约版本;aggregateVersion 是这笔订单的状态版本。前者并不是载荷升级开关,后两者的具体规则由项目定义。([GitHub][3])

本例每次订单状态迁移产生一条事件,状态版本递增。消费者只有订阅完整生命周期事件流,才可用缺号检查遗漏;只订阅确认事件时,不能把没收到创建事件判为丢消息。旧版本事件也不能覆盖已经更新的查询投影。

用样例校验载荷,并约束升级

将主示例和下面的完整脚本分别保存为同一目录下的 order-confirmed.json、check_order.py,从该目录使用 Python 3.10 或更高版本运行 python3 check_order.py。脚本只检查身份关联和金额规则,不替代信封格式、必填字段和时间格式的完整校验;保留时间占位也不会被它识别为错误。

python
import json
from pathlib import Path

event = json.loads(Path("order-confirmed.json").read_text(encoding="utf-8"))
data = event["data"]

# subject 和业务主键必须指向同一笔订单。
if event["subject"] != data["orderId"]:
    raise ValueError("subject 与 orderId 不一致")
if data["currency"] != "CNY" or not data["items"]:
    raise ValueError("本例要求 CNY 且明细非空")

# 拒绝布尔值和小数,避免数量与金额被隐式转换。
for item in data["items"]:
    if type(item["quantity"]) is not int or item["quantity"] <= 0:
        raise ValueError("quantity 必须为正整数")
    if type(item["unitPriceMinor"]) is not int or item["unitPriceMinor"] < 0:
        raise ValueError("unitPriceMinor 必须为非负整数")
if type(data["totalAmountMinor"]) is not int or data["totalAmountMinor"] < 0:
    raise ValueError("totalAmountMinor 必须为非负整数")

# 该等式仅适用于本例不含运费、折扣的金额模型。
expected = sum(item["quantity"] * item["unitPriceMinor"] for item in data["items"])
if data["totalAmountMinor"] != expected:
    raise ValueError("总额与明细不一致")
print("订单身份关联与金额校验通过")

预期输出:

text
订单身份关联与金额校验通过

把总额改为 12901,应得到 ValueError,而不是继续发送事件。重复投递同一事件两次,业务副作用只能提交一次;这一项需要消费者的集成测试,不能从上述字段校验推导出来。

本项目允许在 v1 中增加可选字段,但要求旧读取器忽略未知字段,并约定字段缺失时的行为。删除必填字段、改变金额单位或改变事件业务含义,需要新契约类型并保留迁移窗口,不能只修改 specversion。([GitHub][4])

发布前同时运行“旧消息给新消费者”和“新增可选字段的消息给旧消费者”两组契约样例;涉及库存、扣款等副作用的消费者不能在迁移期间无差别处理新旧两种表示。契约验收应同时覆盖结构、业务含义和消费行为,而不是只确认 JSON 可以解析。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义订单域的事件契约

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

登录哪都通