日志场景不能用同步生产者，因其阻塞goroutine、无法批量、默认不等待确认易丢消息；必须用异步生产者+缓冲区，设RequiredAcks=WaitForAll、Flush.Frequency=100ms、Return.Successes=true，并结构化JSON序列化、定期刷新元数据。
Go 日志中间件对接 Kafka 不是“加个 Producer 就完事”，核心矛盾在于：日志写入必须低延迟、高吞吐，但 Kafka 生产者默认配置极易丢消息、阻塞主线程、或因元数据过期导致批量失败。直接用 sarama.NewSyncProducer 写日志，上线三天必出问题。
为什么日志场景不能用同步生产者
同步生产者（sarama.NewSyncProducer）每次 SendMessage 都会阻塞当前 goroutine，直到 broker 返回响应。日志调用量大、频率高，一旦 Kafka 延迟升高或短暂不可用，整个服务的 HTTP 请求、DB 查询都会被卡住——这不是“日志发不出去”，而是“业务直接卡死”。
-
config.Producer.RequiredAcks默认是sarama.NoResponse，日志看似“发送成功”，其实 broker 连磁盘都没写，重启就丢 - 同步模式下无法做批量攒批（batch），每条日志单独 TCP 包，网络开销爆炸
- 没有重试兜底：超时后直接 panic 或忽略，日志黑洞就此形成
必须用异步生产者 + 自定义日志缓冲区
日志属于“尽力而为但不可丢失”的关键路径，正确做法是：用 sarama.AsyncProducer 接收日志 entry，再由后台 goroutine 持续消费 channel 并批量提交；同时配缓冲区防背压打爆内存。
- 初始化时设
config.Producer.Return.Successes = true和config.Producer.RequiredAcks = sarama.WaitForAll，确保落盘才算成功 - 用
config.Producer.Flush.Frequency = 100 * time.Millisecond控制攒批节奏，避免空等 - 给
AsyncProducer.Input()channel 加缓冲（如make(chan *sarama.ProducerMessage, 1000)），满时丢老日志而非阻塞业务 - 监听
producer.Successes()和producer.Errors()channel，失败日志可降级写本地文件（如/var/log/app/kafka-fallback.log）
日志结构怎么序列化才不踩坑
别用 sarama.StringEncoder 直接包日志字符串——遇到 \x00、换行符、emoji 会截断或解析失败。日志字段必须结构化，且编码方式与 Kafka 消费端约定一致。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 统一用
sarama.ByteEncoder([]byte)，序列化前先 JSON marshal：json.Marshal(map[string]interface{}{"level": "info", "msg": "db timeout", "ts": time.Now().UnixMilli()}) - 日志 key 建议设为 service 名 + 主机名（如
"order-service-host-01"），方便按服务分片消费 - 避免在 value 中塞超大 trace 上下文；大字段走独立 topic 或对象存储，Kafka 单消息默认上限 1MB
- 如果消费端是 Logstash/Fluentd，确认其 Kafka input 插件是否要求
headers携带content-type: application/json，需手动加msg.Headers = append(msg.Headers, sarama.RecordHeader{Key: []byte("content-type"), Value: []byte("application/json")})
Topic 创建和元数据管理最容易被忽略
本地跑通了不代表生产能用。日志 topic 若用 kafka-topics.sh 手动创建，多节点集群中常出现 ISR 数不足、分区 leader 分布不均，导致部分 partition 消息堆积甚至不可读。
- 必须用
sarama.NewClusterAdmin创建 topic，它会实时校验ReplicationFactor是否 ≤ 当前可用 broker 数（例如配 3 副本但只启 2 个 broker，会直接报错） - 日志 topic 建议设
RetentionMs = 604800000（7 天），避免磁盘爆满；MinInSyncReplicas = 2防止单点故障丢数据 - 长期运行的服务要定期调
admin.RefreshMetadata()，否则元数据过期会导致新 partition 无法路由，错误日志里只显示UNKNOWN_TOPIC_OR_PARTITION，极难定位
真正麻烦的不是“怎么把日志发到 Kafka”，而是“怎么让日志在 Kafka 里活过 7 天、被正确消费、且不拖垮业务”。每个环节的默认值都在诱你掉坑——从 RequiredAcks 到 Flush.Frequency，再到 RefreshMetadata 的调用时机，漏一个，线上查日志就像大海捞针。
