Pulsar Topic 详解

Apache Pulsar Topic（主题） 是消息传输的核心逻辑单元，是生产者发布消息、消费者订阅消息的通道。Pulsar 的 Topic 设计非常灵活，支持多种类型、分区、路由策略和存储模型，是其高性能、高可用、多场景适配的关键。

---

📘 Pulsar Topic 详解

---

一、Topic 基本概念

1. 什么是 Topic？

• Topic 是消息的逻辑通道，生产者向其发送消息，消费者从其接收消息。
• 所有消息都必须发送到某个具体的 Topic。
• Topic 是无状态的，其元数据和数据由 Broker 和 BookKeeper 管理。

2. Topic 的命名格式

{persistent|non-persistent}://tenant/namespace/topic

部分	说明
persistent / non-persistent	消息是否持久化存储
tenant	租户名称（如 mycompany）
namespace	命名空间（如 finance）
topic	主题名（如 payments）

示例：

• persistent://mycompany/finance/payments
• non-persistent://public/default/monitoring

---

二、Topic 类型

Pulsar 支持两种主要类型的 Topic：

1. Persistent Topic（持久化 Topic）

• ✅ 默认类型，消息写入 BookKeeper 持久化存储。
• 即使 Broker 重启、消费者离线，消息也不会丢失。
• 支持消息重放、延迟消费、死信队列等高级功能。
• 适用于大多数生产场景（如金融、日志、事件流）。

# 创建（自动创建，无需显式命令）
# 消息路径：Producer → Broker → BookKeeper

2. Non-Persistent Topic（非持久化 Topic）

• ❌ 消息不写入 BookKeeper，仅在内存中缓存。
• 消息生命周期仅限于当前连接期间。
• 如果 Broker 宕机或消费者断开，消息丢失。
• ⚡ 超低延迟，适合监控、实时通知、心跳等场景。

# 使用示例
pulsar://broker:6650/non-persistent://public/default/metrics

⚠️ 注意：Non-persistent Topic 不支持消息重放、TTL、持久订阅。

---

三、Partitioned Topic（分区 Topic）

1. 什么是分区 Topic？

• 一个逻辑 Topic 被拆分为多个 物理子 Topic（Shard），每个分区独立存储和消费。
• 格式：persistent://tenant/namespace/topic-name-partition-X（X 从 0 开始）

# 创建 4 个分区的 Topic
pulsar-admin topics create-partitioned-topic my-topic --partitions 4

2. 分区的作用

优势	说明
🔺 高吞吐	多个分区并行读写，突破单 Broker 性能瓶颈
🔺 水平扩展	分区可分布在不同 Broker 上，实现负载均衡
🔺 并行消费	每个分区可由一个消费者线程处理，提升消费速度

3. 消息路由策略（Producer 端）

Producer 发送消息时，可通过以下策略决定路由到哪个分区：

策略	说明
RoundRobin	轮询分配（默认）
SinglePartition	固定到某个分区
CustomPartition	自定义哈希函数（如按 Key 哈希）

// Java Producer 示例：按 Key 哈希路由
producer = client.newProducer()
    .topic("my-partitioned-topic")
    .messageRoutingMode(MessageRoutingMode.SinglePartition)
    .hashingScheme(HashingScheme.Murmur3_32Hash)
    .create();

💡 提示：使用 Key_Shared 订阅模式时，相同 Key 的消息总由同一消费者处理，保证顺序性。

---

四、Topic 的生命周期管理

1. 自动创建 vs 手动创建

方式	说明
自动创建（默认）	Broker 配置 allowAutoTopicCreation=true，首次发送消息时自动创建
手动创建	使用 pulsar-admin topics create 显式创建，便于权限和配额控制

# 手动创建非分区 Topic
pulsar-admin topics create persistent://mycompany/finance/orders

# 创建分区 Topic
pulsar-admin topics create-partitioned-topic persistent://mycompany/finance/events --partitions 8

2. 删除 Topic

# 删除非分区 Topic
pulsar-admin topics delete persistent://mycompany/finance/orders

# 删除分区 Topic（会删除所有分区）
pulsar-admin topics delete-partitioned-topic persistent://mycompany/finance/events

⚠️ 注意：删除 Topic 会清除所有消息和订阅游标，不可恢复。

3. 查看 Topic 信息

# 列出命名空间下所有 Topic
pulsar-admin topics list mycompany/finance

# 查看 Topic 状态（连接数、吞吐等）
pulsar-admin topics stats persistent://mycompany/finance/orders

# 查看分区信息
pulsar-admin topics partitioned-stats persistent://mycompany/finance/events

---

五、Topic 与 Subscription（订阅）的关系

一个 Topic 可被多个 独立的 Subscription 订阅，每个订阅有独立的消费进度（Cursor）。

Topic: orders-topic
 ├─ Subscription: sub1 (Exclusive) → Consumer-A
 ├─ Subscription: sub2 (Shared)     → Consumer-B, Consumer-C
 └─ Subscription: sub3 (Failover)  → Primary: D, Backup: E

• 每个 Subscription 独立消费，互不影响。
• 支持重置消费位点、跳过消息、延迟重试等。

# 重置订阅位置
pulsar-admin topics reset-cursor -s sub1 -t "2024-01-01T00:00:00Z" orders-topic

---

六、Topic 高级特性

1. 延迟消息（Delayed Message）

• 消息发送后，延迟一段时间才被消费者看到。
• 适用于定时任务、订单超时等场景。

producer.newMessage()
    .value("delayed task")
    .deliverAfter(10, TimeUnit.MINUTES)
    .send();

实现原理：Broker 将消息暂存到内部 __delay Topic，到期后转发。

2. 消息去重（Deduplication）

• 防止 Producer 重复发送相同消息（如网络重试导致）。
• 启用后，Broker 会记录消息 ID，重复消息被丢弃。

pulsar-admin namespaces set-deduplication mycompany/finance --enable

3. 死信队列（Dead Letter Topic, DLT）

• 消费失败达到最大重试次数后，消息自动转入 DLT。
• 便于后续排查和重处理。

pulsar-admin namespaces set-dead-letter-policy mycompany/finance \
  --maxRedeliverCount 5 \
  --deadLetterTopic mycompany/finance/dlq

4. 消息保留与 TTL

• 即使消息已被消费，也可保留一段时间供重放。
• 支持按时间或大小设置保留策略。

pulsar-admin namespaces set-retention mycompany/finance \
  --time 72h \
  --size 10G

---

七、Topic 使用最佳实践

实践	建议
📌 命名规范	使用小写、连字符，如 user-signup-events
📌 合理分区	高吞吐场景使用分区（4~32 个），避免过多（影响管理）
📌 避免频繁创建/删除	频繁操作影响 ZooKeeper 性能
📌 启用消息去重	对关键业务（如支付）防止重复处理
📌 监控 Topic 指标	关注 backlog（未消费消息）、吞吐、延迟
📌 使用 Schema	为 Topic 定义 Schema（Avro/JSON/Protobuf），保证数据一致性

# 为 Topic 设置 Schema
pulsar-admin schemas upload my-topic --filename user-schema.json

---

八、可视化 Topic 结构示例

persistent://mycompany/finance/payments
│
├── 分区结构（如果是分区 Topic）
│   ├── payments-partition-0 → Bookie 存储
│   ├── payments-partition-1 → Bookie 存储
│   └── payments-partion-2 → Bookie 存储
│
├── 生产者（Producers）
│   └── App-Service-A (通过 Key 哈希路由)
│
├── 消费者组（Subscriptions）
│   ├── sub-payments-processor (Shared)
│   │   ├── Consumer-1
│   │   └── Consumer-2
│   └── sub-audit-log (Exclusive)
│       └── Audit-Service
│
└── 高级策略
    ├── TTL: 48h
    ├── Retention: 72h
    ├── Dead Letter Topic: dlq/payments-failed
    └── Max Redeliver: 3

---

✅ 总结：Pulsar Topic 核心特性

特性	说明
✅ 分层命名	persistent://tenant/namespace/topic
✅ 两种类型	Persistent（持久化）、Non-persistent（低延迟）
✅ 分区支持	提升吞吐与并行处理能力
✅ 多订阅模型	一对多广播、队列消费、主备模式
✅ 高级功能	延迟消息、去重、死信队列、TTL、Schema
✅ 动态管理	CLI/API 支持创建、删除、监控、重置

---

📌 一句话总结：

Topic 是 Pulsar 的“高速公路” —— 它决定了消息如何流动、存储、消费。通过合理设计 Topic 结构、分区策略和订阅模式，可以构建高性能、高可靠的实时数据管道。