主题命名与治理是什么
Kafka 的主题名是长期契约：一旦有消费者按名字订阅、权限按前缀授权、监控按名字配置告警，改名就意味着上下游全量改动，而 Kafka 本身不支持重命名主题，只能新建再迁移。因此命名要能表达环境、所属域与数据用途，并把分区数、副本数、保留策略、负责人一并登记，形成可查的主题清单。
基本信息
| 建议结构 | <环境>.<域>.<实体>[.<版本>]，例如 prod.order.created.v1 |
|---|---|
| 合法字符 | 大小写字母、数字、点、下划线、连字符；不能只有点本身 |
| 长度限制 | 主题名长度上限 249 个字符 |
| 创建参数 | kafka-topics.sh --create 时指定 --partitions 与 --replication-factor |
| 关键属性 | retention.ms、cleanup.policy（delete 或 compact）、max.message.bytes |
| 治理清单 | 负责人、上下游应用、预估吞吐、分区数、保留期、是否含敏感数据 |
典型使用场景
- 新链路接入：按规范确定主题名并登记到主题清单后再创建
- 环境隔离：同一集群内用环境前缀区分生产与测试，配合前缀授权
- 多团队审核：命名评审时确认域归属，避免不同团队用同名主题
- 容量规划：按峰值吞吐与下游并行度预先定分区数，减少后期扩容
- 生命周期治理：识别无消费者、无写入的僵尸主题并下线
命名示例与创建
命名示例与创建
# 命名形态：环境.域.实体[.版本]
prod.order.created.v1
prod.pay.transaction.v2
dev.user.profile.changelog
# 创建主题：分区数按峰值吞吐与下游并行度规划，副本数不超过 broker 数
kafka-topics.sh --bootstrap-server kafka1:9092 --create \
--topic prod.order.created.v1 \
--partitions 12 --replication-factor 3 \
--config retention.ms=604800000 # 保留 7 天
# 查看全部主题与描述，核对实际分区与保留配置
kafka-topics.sh --bootstrap-server kafka1:9092 --list
kafka-topics.sh --bootstrap-server kafka1:9092 --describe --topic prod.order.created.v1命名要素对照
| 要素 | 写法 | 常见错误 |
|---|---|---|
| 环境 | prod / pre / dev 前缀 | 多环境共用集群却不加前缀，误连与权限越界 |
| 域与实体 | order.created、pay.transaction | 用业务缩写造成同义不同名 |
| 版本 | 末尾 .v1、.v2 表示结构变更 | 用日期当版本，消费者与权限无法复用 |
| 变更标记 | changelog、snapshot 等用途后缀 | 同一主题混放全量与增量 |
| 内部主题 | 以 __ 开头，由集群管理 | 误建或误删内部主题 |
主题改名只能新建加迁移：旧名保留一段时间做双写过渡，确认消费方切换完成后再下线，直接删旧主题会造成消费中断。
主题数量失控（每表一主题、每次小改动建新主题）会显著增加运维成本与元数据压力，合并与复用需求应归口评审，而不是让每个团队自行新建。