大数据与流处理 / 系统课时

定义事件与主题

定义事件与主题

本课把交易系统产生的业务变化整理成可长期演进的事件协议,并建立原始、清洗和异常三类 Kafka 主题。完成后,同一笔交易的事件能够保持分区内有序,Flink 作业也能按稳定字段解析和升级。

学习目标

  • 设计包含幂等标识、事件时间和交易载荷的事件结构
  • 为 Kafka 主题选择分区键、分区数和数据保留职责
  • 制定不破坏现有消费者的版本兼容规则

设计事件协议

交易事件应把路由字段放在顶层,把业务字段放入 data。顶层字段尽量稳定,便于日志检索、反序列化和跨事件类型处理;金额使用最小货币单位的整数,避免浮点精度问题。

字段 类型 作用 约束
schemaVersion string 事件结构版本 使用 主版本。次版本
eventId string 全局幂等标识 不得重复
eventType string 业务变化类型 使用受控枚举
eventTime long 事件发生时间 Unix 毫秒
source string 事件来源服务 不随部署实例变化
traceId string 调用链标识 可为空但建议保留
data.transactionId string 交易主键 同时作为 Kafka 消息键
data.amountMinor long 最小货币单位金额 必须大于 0
data.currency string ISO 货币代码 三位大写字母

一条支付成功事件可以采用下面的 JSON。生产者发送时,应把 data.transactionId 同时写入 Kafka record key,而不是只放在消息体中。

json
{
  "schemaVersion": "1.0",
  "eventId": "evt-1001",
  "eventType": "PAYMENT_SUCCEEDED",
  "eventTime": 1767225600123,
  "source": "trade-service",
  "traceId": "trace-9001",
  "data": {
    "transactionId": "tx-20260101-0001",
    "merchantId": "m-100",
    "orderId": "order-9001",
    "amountMinor": 12800,
    "currency": "CNY",
    "payMethod": "CARD",
    "channel": "channel-a"
  }
}

验证时至少检查:JSON 能被解析、必填字段存在、eventId 唯一、金额为正数、事件时间合理,并且消息键等于 transactionId。

协议还必须提前约定升级边界。1.x 版本只做向后兼容变更:新增可选字段、新增事件类型,或放宽不影响旧数据的校验。消费者必须忽略未知字段,并为可选字段设置默认值。

删除字段、修改字段含义、改变金额单位或更换主键都属于破坏性变更,应升级主版本并写入新主题,例如 trade-events-v2。迁移期间可以由生产者双写或由桥接作业转换,待所有消费者完成切换后再停止旧版本。

规划主题与分区

本项目使用三个主题隔离不同质量阶段,避免下游同时承担解析、纠错和业务计算。

交易事件主题与分区流向图

主题 数据内容 主要消费者
trade-events-v1 生产者原始事件 清洗作业、审计回放
trade-events-clean-v1 已解析且通过校验的事件 实时指标、风控和告警
trade-events-dlq-v1 解析或校验失败的原文与原因 数据治理和补偿任务

原始主题应保留足够的回放周期;清洗主题面向稳定下游;异常主题不能只存错误原因,还要保存受控长度的原始消息、来源主题、分区、offset 和失败时间,便于定位与重放。

Kafka 只保证单个分区内的顺序,因此交易状态事件使用 transactionId 作为消息键。同一笔交易的创建、成功、失败或退款事件会进入同一分区,下游才能按到达顺序更新状态。

分区数决定消费并行度上限。本地练习可使用 6 个分区和 1 个副本;生产环境应根据峰值吞吐、单分区处理能力、故障冗余和未来扩容评估,并通常使用至少 3 个副本。主题分区可以增加但不能直接缩减,扩分区还会改变键到分区的映射,因此不要频繁调整。

创建并验证主题

下面命令适合本地单 broker 环境。先把 <PORT> 替换为 Kafka 实际端口;生产环境不要照搬副本数 1。

bash
BOOTSTRAP_SERVER="localhost:<PORT>"

for TOPIC in trade-events-v1 trade-events-clean-v1 trade-events-dlq-v1; do
  kafka-topics.sh \
    --bootstrap-server "$BOOTSTRAP_SERVER" \
    --create \
    --if-not-exists \
    --topic "$TOPIC" \
    --partitions 6 \
    --replication-factor 1
done

kafka-topics.sh \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --describe \
  --topic trade-events-v1

预期输出中的 leader、replica 和 ISR 编号会随集群变化,关键是主题存在且 PartitionCount 为 6。

text
Created topic trade-events-v1.
Created topic trade-events-clean-v1.
Created topic trade-events-dlq-v1.
Topic: trade-events-v1  PartitionCount: 6  ReplicationFactor: 1

如果提示副本数大于可用 broker 数,应降低本地副本数或增加 broker;如果主题已存在但分区数不符,应先确认是否允许扩分区,而不是删除生产主题重建。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义事件与主题

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

登录哪都通