gin + kafka 不该直接用 sarama 默认配置，因其 version 默认为 v0_8_2_0，与现代 kafka（v2.8+）不兼容，导致消息发送失败却无明确报错；必须显式设置匹配 broker 的版本并启动 goroutine 持续消费 errors()/successes() 通道，否则会 panic；gin handler 中需透传 context 超时、手动管理 offset 提交并与业务事务强绑定。
为什么 Gin + Kafka 不该直接用 sarama 默认配置
默认配置下，sarama.NewConfig() 会设 Version = sarama.V0_8_2_0，而现代 Kafka（v2.8+）已废弃该协议字段。现象是：消息发出去了，但消费者收不到，或报 UNKNOWN_TOPIC_OR_PARTITION 却不提示真实原因——错误被吞掉，只在 Errors() 通道返回 nil 或 io.EOF。
必须显式设置匹配 Broker 版本的 config.Version，例如 Kafka v3.5 对应 sarama.V3_5_0_0；否则 ProducerMessage 序列化失败，但调用方无感知。
- 初始化后立刻校验：
if !config.Version.IsAtLeast(sarama.V2_0_0_0) { log.Fatal("Kafka version too low") } - 别信文档里“自动适配”的说法，sarama 不做运行时协商，只按配置版本硬编码序列化逻辑
- Gin 启动时就该加载并校验 Kafka 配置，而不是等到第一个 HTTP 请求才暴露问题
sarama.AsyncProducer 的 Errors() 和 Successes() 必须持续消费
这是 Gin 服务上线后最常导致 panic 的点：sarama.AsyncProducer 内部用无缓冲 channel 投递结果，一旦 Errors() 或 Successes() 没被 goroutine 持续读取，内部 buffer 满后所有 Input() 调用直接 panic，错误信息是 send to closed channel——但实际是 channel 阻塞触发了 producer 自动关闭。
在 Gin handler 中调用 producer.Input() 前，必须确保后台有 goroutine 在消费这两个 channel：
- 启动独立 goroutine，哪怕只是丢弃：
go func() { for range p.Errors() {} }() - 若需记录成功 offset，注意
sarama.ProducerMessage.Metadata只在Successes()中填充，且不是线程安全的，别复用同一 message 实例 - 别在
defer里关 channel 或“等完再关”，AsyncClose()本身会阻塞，前提是有人在读
Gin handler 中调用 Kafka 消费逻辑时，context 超时必须穿透到底层
Gin 的 c.Request.Context() 是请求生命周期的唯一权威信号，但 sarama.ConsumerGroup 不接受 context.Context，而 kafka-go.Reader 原生支持。如果你坚持用 sarama，就必须手动把超时和取消信号转成 time.Timer 或 select 控制循环。
常见错误是：Gin handler 设置了 c.Timeout(30 * time.Second)，但 Kafka 消费逻辑仍在阻塞等待 broker 响应，导致整个请求 hang 死，goroutine 泄漏。
- 对每个
session.ConsumeClaim()循环加select判断 context 是否 done - 避免在
Setup()或Cleanup()里做同步 I/O（如 DB 连接、HTTP 调用），否则会卡住整个 rebalance 流程 - 更稳妥的做法是换用
kafka-go.Reader，它所有阻塞方法都接收context.Context，天然适配 Gin 的中间件链路追踪
offset 提交策略必须脱离 Kafka 自动提交，绑定到业务事务
在 Gin 接口处理中，典型模式是“收到消息 → 更新 MySQL → 写 Redis 缓存 → 提交 offset”。如果依赖 AutoCommit: true，一旦 MySQL 写失败但 offset 已提交，这条消息就永远丢失了；如果手动 commit 却在 panic 后没执行，又会重复消费。
真正能落地的是“At-Least-Once + 幂等消费”，关键在把 offset 提交和业务写入放在同一事务边界内：
- 用数据库事务包裹业务操作 + offset 记录（例如写入 pg 表的
consumer_offsets表） - 禁止在 handler 里调
session.CommitOffsets()后不管返回值，必须检查 error 并重试或告警 -
kafka-go的CommitInterval必须显式设为1 * time.Second，否则依赖ReadMessage()自动提交，panic 时直接丢 offset
最难的不是连上 Kafka，而是当 Gin handler 因正则匹配崩溃、MySQL 连接池耗尽、或 Redis timeout 导致 panic 后恢复时，你的 offset 是否还准、下游系统会不会被同一条消息打穿——这些细节藏在 CommitInterval、handler 的 recover 逻辑和错误重试策略里。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
