10.3.1 主题规划与命名规范

主题规划与命名规范应以业务边界、数据生命周期与运维可读性为核心。规划时先划分业务域与数据类型，区分事件流、日志流、指标流与回放流，避免一个主题承载多种语义。对外部系统接入应建立独立主题与网关层，减少耦合。主题数量控制在可管理范围，遵循“少而清晰”的原则，同时为高频热点业务预留独立主题，避免与低频业务混用导致分区与保留策略冲突。

命名规范需统一、可读、可检索。推荐结构为：<环境>.<业务域>.<子域>.<数据类型>.<版本>。环境建议 dev/stg/prod 等短语；业务域与子域使用小写英文字母与数字，单词以点分隔；数据类型建议使用固定枚举：event/log/metric/cdc/replay；版本用于协议变更与平滑迁移。禁止使用空格、中文、特殊字符与混合大小写，避免与监控、权限与配置工具产生歧义。

示例命名：
- prod.trade.order.event.v1
- stg.payment.refund.log.v1
- prod.shared.user.cdc.v2
- prod.trade.order.retry.v1
- prod.trade.order.dlq.v1

主题规划需与数据治理对齐：为 CDC、延迟队列、死信队列、重试队列分别设置前缀或后缀，如 *.cdc.*、*.retry.*、*.dlq.*，以便路由与运维。对跨系统共享主题使用 shared 子域标识，增强权限隔离与审计可追溯。主题创建应纳入变更流程，包含用途说明、负责人、预期吞吐、保留策略与分区规划，避免无序增长。

安装与准备（示例为 Kafka 3.x，已部署集群）：

# 安装客户端（示例：二进制包）
wget https://archive.apache.org/dist/kafka/3.6.0/kafka_2.13-3.6.0.tgz
tar -zxvf kafka_2.13-3.6.0.tgz
export KAFKA_HOME=$PWD/kafka_2.13-3.6.0
export PATH=$KAFKA_HOME/bin:$PATH

# 验证连接
kafka-broker-api-versions.sh --bootstrap-server 10.0.0.11:9092

主题创建与命名规范落地示例（含命令解释）：

# 1) 创建事件主题：prod.trade.order.event.v1
# --partitions: 初始分区数
# --replication-factor: 副本数
# --config: 关键保留与压缩策略
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic prod.trade.order.event.v1 \
  --partitions 12 --replication-factor 3 \
  --config cleanup.policy=delete \
  --config retention.ms=604800000 \
  --config compression.type=lz4

# 2) 创建重试与死信主题
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic prod.trade.order.retry.v1 \
  --partitions 6 --replication-factor 3 \
  --config retention.ms=86400000

kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic prod.trade.order.dlq.v1 \
  --partitions 3 --replication-factor 3 \
  --config retention.ms=2592000000

命令输出核验与说明：

# 查看主题详情，确认命名与关键配置
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --describe --topic prod.trade.order.event.v1

# 预期效果：
# Topic: prod.trade.order.event.v1  PartitionCount: 12  ReplicationFactor: 3
# Configs: cleanup.policy=delete,retention.ms=604800000,compression.type=lz4

排错要点（结合命令解释）：

# 错误1：命名含非法字符（如空格/中文）
# 现象：InvalidTopicException
# 解决：改为小写英文+点分隔
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic "prod.trade 订单.event.v1"
# 修正：
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic "prod.trade.order.event.v1"

# 错误2：副本数大于Broker数量
# 现象：InvalidReplicationFactorException
# 解决：降低副本数或扩容Broker
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic prod.trade.order.event.v1 \
  --partitions 12 --replication-factor 5
# 修正：
kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic prod.trade.order.event.v1 \
  --partitions 12 --replication-factor 3

实践练习：
1. 规划一个 prod.payment.refund 业务域，设计 event/log/dlq 三类主题，并给出完整命名。
2. 用 kafka-topics.sh --describe 验证每个主题的保留策略与副本数，截图或记录输出。
3. 模拟一次命名错误（含大写或空格），观察报错类型并修正。