消息队列 / 系统课时
Topic 命名与生命周期
Topic 命名与生命周期
Topic 一旦进入生产环境,就会同时被生产者、消费者、监控、权限和运维脚本引用。本篇建立一套可执行的命名规则,并把创建、变更、归档和下线串成可审计流程,避免名字随意增长、语义漂移和误删正在使用的 Topic。
学习目标
- 按环境、业务域、事件类型和主版本设计稳定的 Topic 名称
- 用命令完成创建与校验,并理解哪些变更应新建 Topic
- 建立从启用到归档、删除的生命周期检查项
先固定命名语义
推荐把 Topic 名称拆成四段:<env>.<domain>.<event>.v<major>。例如 prod.order.order-created.v1,分别表达生产环境、订单域、订单已创建事件和主版本 1。
环境用于隔离部署边界;业务域用于明确所有权;事件类型写“已经发生的事实”,比 order-service-message 这类实现名更稳定;主版本只在发生破坏性契约变化时递增,不要把每次新增可选字段都变成新版本。

创建前先检查三个问题
创建 Topic 前应确认三件事:谁拥有它、事件语义是什么、容量与保留策略是什么。名字只解决“它是什么”,分区数、复制因子和保留时间决定运行成本,因此要在创建时一起进入评审。
下面创建一个订单事件 Topic,并立即读取描述结果核对分区与副本。
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预期输出
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 被误删。
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预期结果
Topic: dev.order.order-created.v1 PartitionCount: 6 ReplicationFactor: 1 Configs: <VALUE>本地示例使用单副本便于直接跟做;生产环境应按集群容灾策略设置更高复制因子。删除命令在不同 Kafka 版本和集群配置下可能没有额外文本输出,最终应再次查询并确认 Topic 已不存在。把“谁负责、何时停产、观察多久、何时删除”写进下线单,生命周期管理才真正可追踪。