Pulsar Key_Shared 订阅与消息顺序性详解

在 Apache Pulsar 中，如何保证消息的顺序性 是一个关键问题，尤其在金融交易、用户行为追踪、状态更新等场景中至关重要。

Pulsar 提供了多种订阅模式，但只有 Key_Shared 订阅模式 能在 高吞吐并行消费的同时，保证相同 Key 的消息顺序处理。

---

📘 Pulsar Key_Shared 订阅与消息顺序性详解

---

一、消息顺序性的核心挑战

在分布式消息系统中，常见的矛盾是：

高吞吐（并发消费） ❌ vs ❌ 消息顺序性

• 如果只用一个消费者（Exclusive），能保证全局顺序，但吞吐低。
• 如果多个消费者并行消费（Shared），吞吐高，但消息乱序。

Pulsar 的 Key_Shared 模式完美解决了这一矛盾：
✅ 相同 Key 的消息顺序处理 + ✅ 不同 Key 的消息并行处理

---

二、Key_Shared 订阅模式详解

1. 核心机制

• 消费者组中的多个消费者共享一个订阅。
• Broker 根据 消息的 Key（Message Key） 进行哈希，将相同 Key 的消息始终路由到同一个消费者。
• 不同 Key 的消息可由不同消费者并行处理。

Topic: user-events
│
├── Key: user-1001 → Consumer-A
├── Key: user-1002 → Consumer-B
├── Key: user-1001 → Consumer-A  ← 保证顺序
├── Key: user-1003 → Consumer-C
└── Key: user-1002 → Consumer-B  ← 保证顺序

✅ 结果：Key 级别顺序性（Per-Key Ordering）

---

2. 如何设置 Message Key？

生产者在发送消息时必须设置 key：

// Java Producer 示例
producer.newMessage()
    .key("user-123")           // 关键：设置 Key
    .value("user login event")
    .send();

⚠️ 如果不设置 Key，消息将被随机分配，无法保证顺序。

---

3. Key_Shared 的消费者配置

Consumer<String> consumer = client.newConsumer(Schema.STRING)
    .topic("user-events")
    .subscriptionName("event-processor")
    .subscriptionType(SubscriptionType.Key_Shared)
    .keySharedPolicy(KeySharedPolicy.stickyHash())  // 推荐策略
    .subscribe();

Key_Shared 策略（Policy）：

策略	说明
auto_split	自动分裂负载，动态调整 Key 到消费者的映射
sticky_hash	使用哈希固定分配，减少重分配（推荐）

✅ 推荐使用 sticky_hash，稳定性更好。

---

三、Key_Shared 的顺序性保障

保证	说明
✅ 相同 Key 的消息顺序消费	同一 Key 的消息总由同一消费者处理，天然有序
❌ 全局顺序不保证	不同 Key 的消息可能乱序
✅ 分区内部顺序	即使是分区 Topic，Key 路由也保证一致性

📌 适用场景：用户行为分析、订单状态更新、会话事件流等“按用户/订单 ID 顺序处理”的业务。

---

四、与其他订阅模式的顺序性对比

订阅模式	并发消费	全局顺序	Key 级顺序	高吞吐	容错性	典型场景
Exclusive	❌ 单消费者	✅ 严格顺序	✅	❌ 低	❌ 无	单实例任务
Failover	❌ 主备切换	✅ 严格顺序	✅	⚠️ 中等	✅ 高	顺序 + HA
Shared	✅ 多消费者	❌ 无序	❌	✅ 高	✅ 高	高吞吐队列
Key_Shared	✅ 多消费者	❌ 无序	✅ Key 级顺序	✅ 高	✅ 高	分区顺序处理

---

🔍 详细对比说明

模式	顺序性表现
Exclusive	所有消息按发送顺序消费，严格全局顺序，但无法扩展。
Failover	主消费者处理所有消息，全局顺序，故障时切换，适合不能并行的场景。
Shared	消息轮询分发，完全无序，但吞吐最高。
Key_Shared	局部顺序：相同 Key 有序，不同 Key 可并行，最佳平衡点。

---

五、Key_Shared 的高级特性与注意事项

1. Key 的哈希分配机制

• Broker 使用哈希函数（如 Murmur3）将 Key 映射到消费者。
• 默认使用 JavaStringHash，可配置。

.hashingScheme(HashingScheme.Murmur3_32Hash)

2. 消费者动态增减的影响

• 当消费者加入或退出时，Key 到消费者的映射可能重新分配。
• sticky_hash 策略尽量减少重分配。
• 重分配期间可能出现短暂乱序（如消费者重启）。

✅ 建议：生产环境使用固定数量的消费者，避免频繁扩缩容。

3. 与分区 Topic 的结合

Topic: events (4 partitions)
│
├── Partition-0 → Key_Shared 消费者组
├── Partition-1 → Key_Shared 消费者组
├── Partition-2 → Key_Shared 消费者组
└── Partition-3 → Key_Shared 消费者组

• 分区用于提升吞吐。
• Key_Shared 在每个分区内保证 Key 级顺序。

✅ 高吞吐 + 高顺序性保障。

---

六、典型应用场景

场景 1：用户行为追踪

// 所有 "user-1001" 的事件必须顺序处理
producer.newMessage()
    .key("user-1001")
    .value("click → add-to-cart → purchase")
    .send();

→ 使用 Key_Shared，确保同一用户的事件不乱序。

场景 2：订单状态机更新

// 订单状态：created → paid → shipped → delivered
// 必须顺序处理
producer.newMessage()
    .key("order-5001")
    .value("paid")
    .send();

→ Key_Shared 保证状态更新不颠倒。

场景 3：会话（Session）事件流

// 同一会话内的消息必须有序
.key("session-xyz")

---

七、最佳实践建议

实践	建议
✅ 必须设置 Message Key	否则 Key_Shared 退化为 Shared
✅ 使用有意义的 Key	如 user-id, order-id, session-id
✅ 选择 sticky_hash 策略	减少重分配
✅ 消费者数量固定	避免频繁扩缩容导致重平衡
✅ 配合 Schema 使用	确保 Key 格式一致
✅ 监控 Key 分布	防止“热点 Key”导致负载不均
✅ 业务幂等性设计	防止重复处理（重试场景）

🔥 热点 Key 问题：某个 Key 消息量极大，导致单个消费者过载。
解决方案：拆分 Key、限流、或使用 auto_split 策略。

---

八、可视化：Key_Shared 消费流程

+---------------------+
|   Producer          |
| - key: user-1001    |
| - key: user-1002    |
| - key: user-1001    |
+----------+----------+
           |
           v
+----------+----------+
|   Pulsar Broker      |
| - 按 Key 哈希路由     |
|   user-1001 → C1     |
|   user-1002 → C2     |
+----------+----------+
           |
     +-----+-----+
     |           |
     v           v
+----+----+ +----+----+
| Consumer | | Consumer |
|    C1    | |    C2    |
+---------+ +---------+
  ↑   ↑         ↑   ↑
  |user-1001    |user-1002
  |user-1001    |user-1002

相同 Key 始终由同一消费者处理，保证顺序。

---

✅ 总结

特性	说明
✅ Key 级顺序性	相同 Key 的消息严格有序
✅ 高吞吐	多消费者并行处理不同 Key
✅ 容错性好	消费者可动态加入/退出
✅ 适合事件溯源	用户、订单、会话等场景
⚠️ 不保证全局顺序	不同 Key 之间可能乱序
⚠️ 热点 Key 风险	需监控与治理

📌 一句话总结：

Key_Shared 是 Pulsar 中“鱼与熊掌兼得”的订阅模式 —— 它让你在享受高吞吐并行消费的同时，依然能保证关键业务（如用户、订单）的消息顺序性。