*Redis XGROUP CREATE 命令

XGROUP CREATE 用于为 Stream 创建一个新的消费组，定义消费者共同消费消息的起始点。

---

*语法

XGROUP CREATE key group <id | $> [MKSTREAM] [ENTRIESREAD entries-read]

---

*参数说明

参数	类型	必填	说明
key	String	是	Stream 键名
group	String	是	消费组名称（同一 Stream 内唯一）
id / $	String	是	起始 ID；$ 表示从最后一条开始，0 表示从头开始
MKSTREAM	Flag	否	Stream 不存在时自动创建空 Stream
ENTRIESREAD	Integer	否	设置逻辑读计数器（用于 lag 追踪，Redis 7.0+）

---

*返回值

• OK：消费组创建成功
• Error：参数错误、BUSYGROUP（组已存在）、key 不是 Stream 等

---

*时间复杂度

O(1)

*

*示例

*从头开始消费

> XADD mystream * field1 value1
"1638125000000-0"
> XGROUP CREATE mystream mygroup 0
OK
> XREADGROUP GROUP mygroup Alice COUNT 1 STREAMS mystream >
1) 1) "mystream"
   2) 1) 1) "1638125000000-0"
      2) 1) "field1"
         2) "value1"

*从最新消息开始（仅消费创建后新增的消息）

> XGROUP CREATE mystream mygroup $
OK
> XREADGROUP GROUP mygroup Bob COUNT 1 STREAMS mystream >
1) 1) "mystream"
   2) (empty array)
> XADD mystream * newmsg hello
"1638126000000-0"
> XREADGROUP GROUP mygroup Bob COUNT 1 STREAMS mystream >
1) 1) "mystream"
   2) 1) 1) "1638126000000-0"
      2) 1) "newmsg"
         2) "hello"

*自动创建 Stream

> XGROUP CREATE newstream mygroup $ MKSTREAM
OK
> XLEN newstream
(integer) 0

---

*常见错误

错误	原因	解决
BUSYGROUP	同名消费组已存在	使用唯一名称或先删除旧组
ERR no such key	Stream 不存在且未加 MKSTREAM	创建 Stream 或添加 MKSTREAM
WRONGTYPE	key 不是 Stream 类型	确认 key 的数据类型

---

*最佳实践

• 组名建议包含业务语义，如 order-processors、email-senders
• 新消费者首次上线时，根据需求选择 0（全量）或 $（增量）
• 使用 MKSTREAM 避免 Stream 不存在时的初始化失败
• 同一消费组内的消费者通过 XREADGROUP 自动竞争消息，天然实现负载均衡
• 需要多个独立消费副本时，创建多个消费组（如 group-a、group-b）

---

*FAQ

Q1: 同一 Stream 可以创建多个消费组吗？ A: 可以。每个消费组独立维护 last-delivered-id 和 PEL，互不影响，适合多副本消费场景。

Q2: $ 和 0 有什么区别？ A: $ 表示从 Stream 当前最后一条消息的下一个开始消费，只接收新消息；0 表示从第一条开始消费全部历史消息。

Q3: 创建组后可以修改起始 ID 吗？ A: 不能直接修改。需要使用 XGROUP SETID 重置，但这会重置 PEL，需谨慎操作。