使用go-redis/v8操作Redis Stream必须初始化consumer group、正确处理pending消息并严格校验Values类型为map[string]string，否则易卡死或丢消息；ID设"*"自增，建group用XGroupCreate，读取用XReadGroup配Block超时，ACK后需XPending兜底。
直接用 github.com/go-redis/redis/v8 + XAdd/XReadGroup 就能跑通，但不初始化 consumer group、不处理 pending、乱传 Values 类型，十有八九会卡死或丢消息。
写入 Stream 必须用 XAddArgs，且 Values 只接受 map[string]string
常见错误是把 map[string]interface{} 直接塞进 Values 字段，go-redis/v8 不报错但实际不写入——它静默跳过非 string 类型的 value。你看到 XLEN 为 0 或日志里没报错却查不到消息，大概率是这原因。
-
ID设为"*"让 Redis 自增；调试时可用"0-0"强制前置（生产禁用） -
MaxLen建议设具体值（如10000），避免内存无限增长；MaxLenApprox更友好，允许 Redis 略微超限 - 务必带超时 context：
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)，否则网络抖动会卡住 goroutine - 别省略
Stream字段名——它是必填项，漏了XAdd返回空 ID 且无提示
XReadGroup 前必须手动建 group，否则返回空结果且不报错
XReadGroup 不会自动创建 consumer group。如果没提前调 XGROUP CREATE，它就安静地返回空 slice，看起来像“没消息”，其实是 group 根本不存在。很多线上问题都卡在这步。
- 建 group 的最小必要调用：
client.XGroupCreate(ctx, "mystream", "mygroup", "0").Err() - consumer name（第三个参数）不能含空格、斜杠、控制字符，否则
XReadGroup静默失败 - 首次读取用
Start: "0"；后续读取用上一条消息 ID 拼"-1"（如"1678886400000-0"→"1678886400000-1"），防止漏消息 - 阻塞读必须显式设
Block: 5000（单位毫秒），不设就是非阻塞轮询，CPU 白耗
ACK 不是保险丝，得靠 XPending 定期兜底
XAck 成功只代表 Redis 把消息从 pending 列表移出，不代表业务逻辑真的成功了。如果 ACK 后 panic，消息就丢了；如果业务成功但 ACK 失败，消息会滞留在 pending 里，下次还可能分给你。
-
XAck参数顺序固定：stream name、group name、message IDs（必须是原始返回的字符串，不能截断或转格式） - 别在
defer里统一 ACK——handler panic 时 defer 不执行，消息永久卡死 - 必须另起 goroutine 定期调
XPending扫描 idle 超时的消息（比如 >30s），再用XClaim抢回重试 - 扫
XPending时注意指定Idle和Count，不然可能拉回全部 pending 消息，压垮消费者
别用 github.com/redis/go-redis/v9，已知消费延迟飙升
实测对比显示，v9 版本在高并发消费场景下，平均延迟比 v8 高 3–5 倍。根本原因是其内部连接复用策略变更，导致 XReadGroup 阻塞等待响应时更容易陷入长轮询假死。
- 坚持用
github.com/go-redis/redis/v8（注意是go-redis，不是redis/go-redis） - 连接池配置别太激进：
PoolSize: 20足够应付多数中等流量服务，设太高反而增加 Redis 连接压力 - Stream 名、group 名、consumer 名建议全小写+下划线，规避大小写和特殊字符兼容性问题
最易被忽略的一点：Redis Stream 的消息 ID 是「毫秒时间戳-序列号」，不是纯递增整数。如果你依赖 ID 做时间范围查询（比如查某分钟内的消息），必须用 XRANGE + 时间戳区间，而不是靠 ID 数值大小做判断——因为同一毫秒内多条消息的序列号部分会不同，跨毫秒时序才绝对可靠。
