Topic命名规范：命名规则与最佳实践、分层命名法、环境标识与业务域划分
说实话，我见过太多Kafka集群因为Topic命名混乱而变成「垃圾场」的案例。有一次我去一家公司做技术咨询，他们的Kafka上有800多个Topic，光看名字根本分不清哪个是哪个。有的叫test，有的叫log，还有的叫data_final_v3_really_final——你想想看，这谁受得了？
Topic命名这事，看似简单，实则坑很多。一个好的命名规范，能让你的团队省下大量排查问题的时间。今天我就把这些年积累的经验和教训，一次性讲清楚。
为什么Topic命名这么重要？
Kafka本身对Topic名字没什么限制，除了不能使用特殊字符、长度不超过249个字符这些基本规则。但正是这种「自由」，反而容易出问题。
我个人的习惯是：把Topic命名当成API设计来做。为什么？因为Topic本质上就是数据管道，生产者和消费者都依赖它。名字起得不好，后期改起来成本极高——你没法直接重命名Topic，只能新建一个再迁移数据。
核心原则：Topic命名应该具备自描述能力。任何人看到这个名字，就能知道：这是什么数据、从哪里来、到哪里去、属于哪个环境。
分层命名法：我的推荐方案
经过多次踩坑和迭代，我现在最推荐的是分层命名法。说白了，就是用约定的分隔符把Topic名字拆成几个有意义的段。
基本结构如下：
{环境标识}.{业务域}.{数据域}.{数据实体}.{事件类型}.{版本}举个例子：
prod.order.ods.order_created.v1
test.payment.dwd.payment_success.v2
dev.user.dim.user_profile.v1每个段都有明确的含义。我来逐一拆解：
| 层级 | 说明 | 示例值 | 注意事项 |
|---|---|---|---|
| 环境标识 | 区分部署环境 | prod, test, dev |
必须小写，不要用production这种长词 |
| 业务域 | 所属业务线 | order, user, payment |
与公司组织架构对齐 |
| 数据域 | 数据分层 | ods, dwd, dws, dim |
参考数据仓库分层标准 |
| 数据实体 | 具体业务对象 | order_created, payment_success |
用下划线连接多个单词 |
| 事件类型 | 操作类型（可选） | created, updated, deleted |
CDC场景常用 |
| 版本 | Schema版本 | v1, v2 |
兼容性变更时递增 |
我的经验：版本号不要一开始就加上。等确实需要做不兼容的Schema变更时再加。我见过有人每个Topic都带v1，结果两年了还是v1，纯属多余。
环境标识：别让测试数据污染生产
这一点我必须重点强调。我曾经在一个项目里遇到过——测试环境的消费者误连了生产环境的Topic，结果把一堆测试数据写进了生产库。那场面，简直灾难。
所以，环境标识必须作为Topic名的第一个段。我推荐用这三个：
prod— 生产环境，数据敏感，权限严格test— 测试环境，模拟真实数据dev— 开发环境，可以随意折腾
有人会问：那staging、uat这些环境呢？我的建议是：能用test就别造新词。环境标识越少越好，否则命名规范会变得臃肿。
避坑指南：我曾经见过有人用prd、tst、dev这种缩写。结果新来的同事把prd看成了prod，把tst当成了test——其实没错，但就是容易混淆。我建议直接用全称，别省那两三个字符。
业务域划分：跟组织架构走
业务域怎么划分？我个人的做法是：直接跟公司的组织架构对齐。
比如你们公司有订单中心、用户中心、支付中心、商品中心，那业务域就是：
prod.order.xxx
prod.user.xxx
prod.payment.xxx
prod.product.xxx这样做的好处很明显：
- 每个团队负责自己的业务域，权限好控制
- 新同事一看就知道这个Topic归哪个团队管
- 跨团队协作时，沟通成本低
但要注意一点：业务域不要分得太细。我见过有人把order_refund和order_return拆成两个业务域，结果后面发现这两个数据经常要一起用，又得做数据合并，麻烦得很。
数据域分层：借鉴数仓思想
如果你做过数据仓库，对这个应该不陌生。Kafka Topic的数据域分层，我建议直接复用数仓的分层标准：
| 分层 | 全称 | 说明 | 示例Topic |
|---|---|---|---|
ods |
操作数据层 | 原始数据，不做任何清洗 | prod.order.ods.order_created.v1 |
dwd |
明细数据层 | 清洗、去重、标准化后的数据 | prod.order.dwd.order_created.v1 |
dws |
汇总数据层 | 轻度聚合，用于报表 | prod.order.dws.daily_order_summary.v1 |
dim |
维度数据 | 维度表数据，变化缓慢 | prod.user.dim.user_profile.v1 |
你可能会问：Kafka又不是数仓，为什么要分层？其实道理是一样的——不同消费者对数据质量的要求不同。有些下游系统需要原始数据自己做处理，有些只需要清洗后的干净数据。分层之后，各取所需，互不干扰。
命名规范的最佳实践清单
说了这么多，我总结一份可以直接拿来用的清单：
- 全小写 — Kafka Topic名是大小写敏感的，全小写能避免手误
- 用点号分隔层级 — 点号在视觉上最清晰，也方便用正则匹配
- 用下划线连接单词 — 实体名里多个单词用下划线，比如
order_created - 不要用连字符 — 连字符在某些工具里会被解析成特殊含义
- 长度控制在80字符以内 — 太长了在监控面板上显示不全
- 版本号只加在末尾 — 不要插在中间，否则解析起来很麻烦
- 禁止使用保留字 — 比如
__consumer_offsets这种内部Topic
一个小技巧：在团队里推行命名规范时，别搞成「霸王条款」。我一般会写一个自动化校验脚本，在CI/CD流程里检查Topic名是否符合规范。不符合的直接拒绝创建，比人工审核靠谱多了。
知识体系总览
下面这张图把Topic命名的核心逻辑串起来了，你可以把它当成一个快速参考：
一个完整的命名示例
最后，我拿一个真实场景来演示。假设你们公司要做订单数据的实时同步：
# 生产环境 - 订单创建事件 - 原始数据
prod.order.ods.order_created.v1
# 生产环境 - 订单创建事件 - 清洗后数据
prod.order.dwd.order_created.v1
# 测试环境 - 订单创建事件 - 原始数据
test.order.ods.order_created.v1
# 生产环境 - 用户维度数据
prod.user.dim.user_profile.v1
# 生产环境 - 支付成功事件 - 汇总数据
prod.payment.dws.daily_payment_summary.v1你看，每个Topic的名字都清清楚楚。运维同学看到prod.order.ods.order_created.v1，就知道：这是生产环境、订单业务线、原始数据层、订单创建事件、第一版。不需要查文档，不需要问人。
嗯，这就是命名规范的价值。说白了，就是用约定代替沟通。团队越大，这个价值就越明显。