Redis XGROUP CREATE MKSTREAM 怎样为不存在的 Stream 建消费组

Redis Stream 还没有写入第一条消息时，直接执行 XGROUP CREATE 通常会因为目标键不存在而失败。解决办法是在命令末尾追加 MKSTREAM，让 Redis 先创建一个长度为 0 的 Stream，再创建消费组。真正决定后续读哪里的是第三个参数：$ 表示从当前末尾之后开始，0-0 表示从头部边界开始。

官方地址：https://redis.io/docs/latest/commands/xgroup-create/

这篇只讨论空 Stream 建组、起始 ID 和重复建组处理，不把消费者接管、消息确认混进同一个问题。

Stream 不存在时为什么需要 MKSTREAM

XGROUP CREATE 需要一个 Stream 键作为消费组的归属对象。默认情况下，键不存在就直接返回错误；追加 MKSTREAM 后，Redis 会创建空 Stream，长度仍然是 0，然后保存消费组名称和起始 ID。

最小命令可以这样写：

# Stream 不存在时，MKSTREAM 负责创建一个空 Stream
redis-cli XGROUP CREATE orders:events order-workers '$' MKSTREAM

成功时命令返回 OK。注意，MKSTREAM 不是“写入一条占位消息”，也不会替你生成业务事件；它只补齐消费组依赖的 Stream 键。

$、0-0 与具体 ID 到底差在哪里

第三个参数是消费组视角下的“最后投递消息 ID”。Redis 官方文档把 $ 定义为当前 Stream 的最后一条消息；因此用 $ 建组时，后续消费者通常只关心建组之后新增的消息。用 0-0 则把组的起点放到最前面，适合需要回放已有消息的场景。

# 只接收建组之后到来的新消息
redis-cli XGROUP CREATE orders:events order-workers '$' MKSTREAM

# 从现有 Stream 的头部边界开始回放
redis-cli XGROUP CREATE orders:events order-replay 0-0 MKSTREAM

# 已知边界时，从指定消息 ID 之后继续
redis-cli XGROUP CREATE orders:events order-retry 1700000000000-0 MKSTREAM

可以用下面的表快速选择：

重复执行时怎样处理 BUSYGROUP

同一个 Stream 内，消费组名称必须唯一。部署脚本重跑或多个实例同时初始化时，第一次创建会成功，后续会收到 BUSYGROUP。这不等于 Stream 损坏，也不应该每次都先销毁消费组再重建，因为销毁会丢失原有的组状态。

# 初始化脚本中的最小幂等策略：已存在就继续，不要销毁重建
if redis-cli XGROUP CREATE orders:events order-workers '$' MKSTREAM 2>group.err; then
  echo "# 消费组创建成功"
else
  # 只有确认错误是 BUSYGROUP 时才按“已经初始化”处理
  if grep -q "BUSYGROUP" group.err; then
    echo "# 消费组已存在，继续后续启动"
  else
    cat group.err
    exit 1
  fi
fi

生产代码里应直接读取客户端返回的错误类型或错误码，而不是只依赖错误文本。若 Stream 名称、组名称或起始 ID 配置错误，仍应让初始化失败并报警。

用 XREADGROUP 核对后续读取边界

建组只是保存消费组元数据，真正读取还要使用 XREADGROUP 指定组名、消费者名和读取位置。新消费者通常用 > 请求尚未投递给该组的消息；读取历史待处理消息时才使用明确的消息 ID。

# 以组成员 worker-1 读取该组尚未投递的新消息
redis-cli XREADGROUP GROUP order-workers worker-1 COUNT 10 STREAMS orders:events '>'

如果建组使用了 $，而命令执行后马上没有新消息，返回空结果是符合预期的；如果业务要求先处理旧消息，应在建组时使用 0-0，不要指望把读取位置临时改成 0-0 就能改变已经保存的组起点。

最后记住这四个判断

• 键不存在：在 XGROUP CREATE 末尾加 MKSTREAM。
• 只收新消息：用 $；要回放历史：用 0-0。
• 重复初始化遇到 BUSYGROUP：保留原组状态，按幂等成功处理。
• 需要验证读取边界：用 XREADGROUP 检查组名、消费者名和 > 的语义。

常见问题

MKSTREAM 会不会自动创建第一条消息？

不会。它只创建长度为 0 的 Stream，业务消息仍需由 XADD 写入。

为什么建组成功但读不到旧消息？

最常见原因是起始 ID 使用了 $。如果需要回放建组前的消息，应在创建组时选择 0-0，并为重复处理准备幂等逻辑。