大数据与流处理 / 系统课时
定义事件与主题
定义事件与主题
本课把交易系统产生的业务变化整理成可长期演进的事件协议,并建立原始、清洗和异常三类 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,而不是只放在消息体中。
{
"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。
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。
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;如果主题已存在但分区数不符,应先确认是否允许扩分区,而不是删除生产主题重建。