XAdd和XReadGroup是Redis Stream生产环境关键函数，错用会导致丢消息、重复消费或goroutine卡死；必须严格校验group创建、ID格式、ACK时机及XPending兜底机制。
XAdd 和 XReadGroup 是生产环境必须用对的两个函数，错一个就可能丢消息、重复消费或卡死 goroutine。别信“先跑通再优化”的说法——Stream 的语义约束强，初始化阶段写错，后期排查成本远高于 upfront 修正。
为什么 XAdd 要用 map[string]string，不能传 map[string]interface{}
go-redis/v8 的 XAdd 明确要求 Values 字段是 map[string]string，不是 map[string]interface{}。传后者不会编译报错，但运行时会 panic 或静默丢键值（取决于 go-redis 版本），且错误信息模糊，常表现为 “invalid argument” 或空消息体。
- 必须显式转换：遍历原始结构体或 map，用
fmt.Sprintf("%v")或json.Marshal转成 string 值 -
ID字段别设为""—— 空字符串会被 Redis 拒绝；设为"*"让服务端自增，或按需构造如"1712345678900-0"这类毫秒时间戳+序列号格式 - 务必检查
XAdd返回值：err != nil时 ID 可能为空，直接用会导致后续XAck失败
为什么 XReadGroup 必须先创建 consumer group，且不能跳过 xinfo 校验
调用 XReadGroup 前，Redis 不会自动创建 consumer group。如果 group 不存在，命令返回空结果，也不报错——这是最隐蔽的翻车点。你看到“没消息”，其实是因为 group 根本没建好。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 首次使用前，必须显式执行
rdb.XGroupCreate(ctx, streamName, groupName, "0").Err() - 创建后立刻用
rdb.XInfoGroups(ctx, streamName).Result()检查 group 是否在列表里，避免因并发或网络重试导致创建失败却未感知 - consumer name 不能含空格、斜杠、控制字符，否则
XReadGroup静默失败，日志里连 warning 都没有 -
Start参数第一次用"0"，之后必须用上一条消息 ID 加"-1"（例如"1712345678900-0"→"1712345678900-1"），否则漏消息
ACK 不是保险丝，XPending 才是兜底关键
XAck 成功只代表 Redis 把消息从 pending list 移出，不代表业务逻辑成功。如果 ACK 后 panic 或进程退出，消息就丢了；如果业务成功但 ACK 失败，消息会留在 pending list 里，下次仍可能被分发——这正是为什么不能依赖 ACK 做唯一确认。
- 必须定期（比如每 30 秒）调用
rdb.XPending(ctx, &redis.XPendingArgs{...}).Result()扫描 pending 消息 - 对 idle 超时（如 > 5 分钟）的消息，主动 re-read 并重试处理，而不是等它自动超时
-
XAck参数里的 message ID 必须和XReadGroup返回的原始字符串完全一致，截断、补零、格式化都会导致 ACK 失效 - 别在
defer里统一 ACK —— handler panic 时 defer 不执行，消息永久卡死
XAdd，而是让整个消费链路在失败、重启、网络抖动下依然可追溯、可重放、不丢不重。所有“自动”“默认”“应该可以”的假设，在 Stream 场景里基本都得亲手验证。 
