sarama.NewConfig()必须显式设置Version，否则默认V0_8_2_0与现代Kafka（v2.8+）协议不兼容，导致消息发送成功但消费者收不到或报UNKNOWN_TOPIC_OR_PARTITION；AsyncProducer的Successes/Errors通道须持续消费，否则内部buffer满引发panic；ConsumerGroup需匹配broker的session.timeout.ms与heartbeat.interval.ms，避免误触发rebalance。
sarama 是当前 Go 生态中事实标准的 Kafka 客户端，它不依赖 CGO，纯 Go 实现，但配置细节多、错误反馈隐晦——直接用默认配置跑通 demo 很容易，一到生产环境就掉坑里。
为什么 sarama.NewConfig() 必须显式设置 Version
不设 config.Version 时，sarama 默认用最低兼容版本（V0_8_2_0），而现代 Kafka 集群（v2.8+）已弃用旧协议字段（如 timestamp、headers）。现象是：消息看似发送成功，但消费者收不到，或报错 UNKNOWN_TOPIC_OR_PARTITION 却不提示真实原因。
- 必须根据 Kafka Broker 版本反查
sarama支持的最高版本，例如 Kafka v3.5 对应sarama.V3_5_0_0 - 版本 mismatch 会导致
ProducerMessage序列化失败，但错误被吞掉，只在Errors()通道返回空指针或io.EOF - 建议在初始化 config 后立刻加校验：
if !config.Version.IsAtLeast(sarama.V2_0_0_0) { log.Fatal("Kafka version too low") }
sarama.AsyncProducer 的 Successes/Errors 通道必须持续消费
异步生产者把发送结果投递到两个无缓冲 channel：Successes() 和 Errors()。如果任一通道没被 goroutine 持续读取，AsyncProducer 内部 buffer 会满，后续所有 Input() 调用直接 panic —— 错误信息是 send to closed channel，但实际是 channel 阻塞导致 producer 自动关闭。
- 必须启动独立 goroutine 消费这两个 channel，哪怕只是丢弃：
go func() { for range p.Successes() {} }() - 不要在 defer 中关 channel 或试图“等完再关”，
AsyncProducer.AsyncClose()本身会阻塞直到内部队列清空，但前提是 Successes/Errors 有人读 - 若需追踪 offset，注意
sarama.ProducerMessage的Metadata字段只在Successes()中填充，且不是线程安全的，别在多个 goroutine 里复用同一 message 实例
ConsumerGroup 重启时 Offset 提交失败的常见诱因
用 sarama.NewConsumerGroup 实现消费者组时，常遇到 rebalance 后新实例从老 offset 开始重复消费，或 offset 根本不提交。根本原因不是代码逻辑错，而是 broker 端配置和客户端超时不匹配。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
-
session.timeout.ms（Broker）必须 ≤config.Consumer.Group.Session.Timeout（客户端），否则 broker 认为 consumer 失联，触发 rebalance -
heartbeat.interval.ms（Broker）必须 session.timeout.ms，且客户端config.Consumer.Group.Heartbeat.Interval要与之对齐，否则心跳发不出去 - offset 提交失败时，
consumer.CommitOffsets()不报错，但日志里会有OffsetCommit failed: UNKNOWN_MEMBER_ID—— 这说明 member id 已失效，必须等下一次 JoinGroup 成功后再提交
Kafka Topic 分区数与 Go 并发模型的隐性冲突
一个 Topic 有 N 个 Partition，sarama ConsumerGroup 会自动分配 partition 给各 consumer 实例。但如果你在每个 ConsumeClaim 回调里起大量 goroutine 处理单条消息，反而可能压垮 broker 连接或本地内存。
立即学习“go语言免费学习笔记（深入）”；
- 每个 partition 对应一个独立的网络连接和内存 buffer，过多 goroutine 会导致 TCP 连接数爆炸（尤其当 consumer 实例数 × partition 数 × goroutine 数 > 1000）
- 推荐做法：每个
ConsumeClaim启动固定数量 worker（如 4~8 个），用带缓冲 channel 控制并发，避免无节制 spawn - 分区数不是越多越好 —— 如果业务处理耗时波动大，某些 partition 积压严重，而其他 partition 空闲，
sarama默认的StickyBalanceStrategy无法动态再平衡，得靠手动Assignor或外部调度
