绝大多数生产场景该用 sarama.NewConsumerGroup，它支持自动分区再均衡、偏移量自动提交、多实例水平扩展；NewConsumer 是单消费者单分区硬绑定模式，需手动管理 offset，仅适用于调试或极简测试。
用 sarama.NewConsumerGroup 还是 sarama.NewConsumer？
绝大多数生产场景该用 NewConsumerGroup，不是 NewConsumer。前者支持自动分区再均衡、偏移量自动提交（可选）、多实例水平扩展；后者是“单消费者-单分区”硬绑定模式，连 offset 管理都要自己手写，只适合调试或极简测试。
- 如果你启动多个进程消费同一个 topic，
NewConsumer会重复消费全部消息——它根本不知道其他实例存在 -
NewConsumerGroup依赖 group.id 和 broker 的协调机制，同一 group 下各实例自动分摊分区，挂掉一个会触发 rebalance -
NewConsumer不维护 group state，无法使用 Kafka 自带的__consumer_offsets存储位置，重启后得靠代码里写死OffsetOldest或OffsetNewest
sarama.Config.Version 必须设对，否则连接直接失败
Kafka 协议版本不匹配时，sarama 可能静默断连、卡在 handshake 阶段，或报错 invalid request type / unsupported version —— 这不是网络问题，是协议握手失败。
- 别用
sarama.DefaultVersion：它对应很老的 Kafka 版本（0.8.x），2024 年后集群基本都不兼容 - 查你 Kafka 服务端版本：比如
3.6.0对应sarama.V3_6_0_0；2.8.1对应sarama.V2_8_1_0 - 如果不确定，宁可往低了设（如设成
V2_8_0_0），也不要设高；高版本配置发低版本 broker 会拒收 - 错误示例：
config.Version = sarama.ParseKafkaVersion("3.7")会 panic，因为 sarama 目前（v1.35）最高只支持到V3_6_0_0
消费者组初始化失败的三个高频原因
调 sarama.NewConsumerGroup 返回 nil 或 panic，常见于配置/网络/权限三类硬伤，不是代码逻辑问题。
- broker 地址写成
"localhost:9092"但 Go 程序跑在 Docker 容器里 → 改成宿主机 IP 或 Kafka 配置advertised.listeners - 没开 SASL/SSL 但集群强制认证 → 报错含
failed to find SASL mechanism或TLS handshake timeout，需配config.Net.SASL或config.Net.TLS - group.id 含非法字符（如空格、下划线开头、长度超 249 字节）→ Kafka 拒绝注册，日志里可能只显示
UnknownMemberId - topic 不存在且
config.Metadata.Retry.Max太小（默认 3 次），首次 fetch metadata 就失败退出 → 建议显式设config.Metadata.Retry.Max = 5
消息循环里别漏掉 session.Context() 和 claim.Messages() 的阻塞特性
ConsumerGroupHandler 的 ConsumeClaim 方法里，claim.Messages() 返回的是一个阻塞 channel，不手动控制退出条件，协程会永远 hang 住，导致程序无法 graceful shutdown。
立即学习“go语言免费学习笔记（深入）”；
- 必须用
for { select { case msg := 包裹，否则 <code>Close()不生效 - 不要在
Messages()外层加range：它底层是无限 for-loop + channel recv，range 会卡死 - 处理完每条消息后，如需手动提交 offset，调
session.MarkMessage(msg, "")；否则依赖自动提交（需开config.Consumer.Group.Rebalance.Strategy和config.Consumer.Offsets.AutoCommit.Enable） - 注意
msg.Value是 []byte，直接string(msg.Value)没问题，但别反复转换——大消息会额外分配内存
