消息队列 / 系统课时

Topic 命名与生命周期

Topic 命名与生命周期

Topic 一旦进入生产环境,就会同时被生产者、消费者、监控、权限和运维脚本引用。本篇建立一套可执行的命名规则,并把创建、变更、归档和下线串成可审计流程,避免名字随意增长、语义漂移和误删正在使用的 Topic。

学习目标

  • 按环境、业务域、事件类型和主版本设计稳定的 Topic 名称
  • 用命令完成创建与校验,并理解哪些变更应新建 Topic
  • 建立从启用到归档、删除的生命周期检查项

先固定命名语义

推荐把 Topic 名称拆成四段:<env>.<domain>.<event>.v<major>。例如 prod.order.order-created.v1,分别表达生产环境、订单域、订单已创建事件和主版本 1。

环境用于隔离部署边界;业务域用于明确所有权;事件类型写“已经发生的事实”,比 order-service-message 这类实现名更稳定;主版本只在发生破坏性契约变化时递增,不要把每次新增可选字段都变成新版本。

Topic 命名结构与生命周期

创建前先检查三个问题

创建 Topic 前应确认三件事:谁拥有它、事件语义是什么、容量与保留策略是什么。名字只解决“它是什么”,分区数、复制因子和保留时间决定运行成本,因此要在创建时一起进入评审。

下面创建一个订单事件 Topic,并立即读取描述结果核对分区与副本。

bash
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic dev.order.order-created.v1 --partitions 6 --replication-factor 1
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic dev.order.order-created.v1

预期输出

text
Created topic dev.order.order-created.v1.
Topic: dev.order.order-created.v1    PartitionCount: 6    ReplicationFactor: 1    Configs: <VALUE>
Topic: dev.order.order-created.v1    Partition: 0    Leader: <ID>    Replicas: <VALUE>    Isr: <VALUE>
...

实际 Leader、Replica、ISR 和 Configs 会随集群状态不同而变化。创建完成后还应由生产者和消费者负责人共同确认名称、分区键和事件契约,避免 Topic 已被代码依赖后再改名。

变更时区分兼容与破坏性修改

能保持事件含义不变、旧消费者仍可继续处理的修改,通常留在同一 Topic,例如增加可选字段、补充可忽略的元数据。Topic 名字保持稳定,消息模式按兼容规则演进。

如果事件语义改变、主键含义改变、关键字段类型不兼容,或消费者必须改代码才能理解新消息,就应创建新的主版本,例如从 prod.order.order-created.v1 切换到 prod.order.order-created.v2。迁移期间可双写或桥接,但要明确结束时间,避免两个版本长期并存。

归档与下线要先证明没人再依赖

下线不是“没人提到就删除”。先停止新增生产流量,再观察消费者组、吞吐和告警,确认没有活跃依赖;随后进入归档期,保留足够时间用于补数、审计或回滚。

真正删除前应保留变更记录,并确认 broker 允许 Topic 删除。执行删除命令前最好再次 --describe,核对名称,防止同域下相似 Topic 被误删。

bash
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic dev.order.order-created.v1
kafka-topics.sh --bootstrap-server localhost:9092 --delete --topic dev.order.order-created.v1

预期结果

text
Topic: dev.order.order-created.v1    PartitionCount: 6    ReplicationFactor: 1    Configs: <VALUE>

本地示例使用单副本便于直接跟做;生产环境应按集群容灾策略设置更高复制因子。删除命令在不同 Kafka 版本和集群配置下可能没有额外文本输出,最终应再次查询并确认 Topic 已不存在。把“谁负责、何时停产、观察多久、何时删除”写进下线单,生命周期管理才真正可追踪。

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

目录与阅读设置

阅读设置

17

记录一个想法

Topic 命名与生命周期

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

登录哪都通