package queue import ( "context" "errors" "fmt" "strings" "sync" "time" "github.com/IBM/sarama" "go.uber.org/zap" ) // 起步 offset 模式(Day58:起步 offset 可配,dev 存量治理配套)。 const ( OffsetModeOldest = "oldest" // 最早(历史积压回放;生产默认语义) OffsetModeLatest = "latest" // 最新(跳过积压;dev 止血用) ) // Handler 消息处理函数:返回 nil 视为处理成功并提交 offset; // 返回错误则不提交(at-least-once,重平衡/重启后重新投递)。 type Handler func(ctx context.Context, msg *sarama.ConsumerMessage) error // ConsumerConfig 消费者组配置。 type ConsumerConfig struct { Brokers []string GroupID string Topics []string Handler Handler Logger *zap.Logger // OffsetMode 起步 offset:oldest|latest(大小写不敏感,非法值创建报错)。 // 仅对无已提交 offset 的消费组生效(新组/offset 重置后);显式指定时 // 优先于 Oldest bool;空则回退 Oldest 语义(历史调用方兼容)。 OffsetMode string Oldest bool // true 从最早 offset 开始(新组/集成测试);默认从最新 // CommitEveryN 每成功处理 N 条显式提交一次 offset(默认 100)。 CommitEveryN int // WorkersPerPartition 每分区并行 worker 数(Day 65;默认 0/1=串行原行为)。 // >1 时同分区消息乱序并行处理,offset 按连续前缀有序 Mark——at-least-once // 语义不变(失败不 Mark 由后继越过;退出/重平衡窗口内不 Mark 的在途消息重投)。 // 适用:单条处理为 DB 慢事务链(sms-submit Deferred 补全),吞吐=并发÷延迟。 WorkersPerPartition int // PaceEvery/PaceSleep 消费 pacing(Day58):每成功处理 PaceEvery 条 // sleep PaceSleep(默认 0=不限速)。冷启动 oldest 存量回放时压制消费 // 速率,防落库风暴打爆下游(dev MySQL);等待可被会话取消即时打断。 PaceEvery int PaceSleep time.Duration } // resolveInitialOffset 解析起步 offset:OffsetMode 显式优先(非法值报错, // 防误配 oldest 引发存量回放风暴);空回退 Oldest bool;默认最新。 func (c ConsumerConfig) resolveInitialOffset() (int64, error) { if c.OffsetMode != "" { switch strings.ToLower(strings.TrimSpace(c.OffsetMode)) { case OffsetModeOldest: return sarama.OffsetOldest, nil case OffsetModeLatest: return sarama.OffsetNewest, nil default: return 0, fmt.Errorf("queue: offset_mode 非法 %q(合法:oldest|latest)", c.OffsetMode) } } if c.Oldest { return sarama.OffsetOldest, nil } return sarama.OffsetNewest, nil } // Consumer 消费者组封装:自动应对重平衡,手动提交 offset。 type Consumer struct { group sarama.ConsumerGroup cfg ConsumerConfig log *zap.Logger } // NewConsumer 创建消费者组(连接 broker)。 func NewConsumer(cfg ConsumerConfig) (*Consumer, error) { if len(cfg.Brokers) == 0 { return nil, errors.New("queue: kafka.brokers 不能为空") } if cfg.GroupID == "" { return nil, errors.New("queue: group_id 不能为空") } if len(cfg.Topics) == 0 { return nil, errors.New("queue: topics 不能为空") } if cfg.Handler == nil { return nil, errors.New("queue: handler 不能为空") } if cfg.CommitEveryN <= 0 { cfg.CommitEveryN = 100 } if cfg.Logger == nil { cfg.Logger = zap.NewNop() } initial, err := cfg.resolveInitialOffset() if err != nil { return nil, err } sc := sarama.NewConfig() sc.Version = sarama.V2_8_0_0 sc.Consumer.Offsets.AutoCommit.Enable = false // 手动提交 sc.Consumer.Offsets.Initial = initial // 起步 offset(Day58 可配;仅新组/重置后生效) sc.Consumer.Group.Heartbeat.Interval = 3 * time.Second sc.Consumer.Group.Rebalance.Retry.Max = 3 // 重平衡重试 sc.Consumer.Group.Rebalance.Timeout = 60 * time.Second group, err := sarama.NewConsumerGroup(cfg.Brokers, cfg.GroupID, sc) if err != nil { return nil, err } return &Consumer{group: group, cfg: cfg, log: cfg.Logger}, nil } // Run 阻塞消费直至 ctx 取消;正常退出(含 Close 后)返回 nil。 func (c *Consumer) Run(ctx context.Context) error { h := &groupHandler{cfg: c.cfg, log: c.log} for { if err := c.group.Consume(ctx, c.cfg.Topics, h); err != nil { if errors.Is(err, sarama.ErrClosedConsumerGroup) { return nil } return err } if ctx.Err() != nil { return nil } } } // Close 关闭消费者组。 func (c *Consumer) Close() error { return c.group.Close() } // groupHandler sarama.ConsumerGroupHandler 实现。 type groupHandler struct { cfg ConsumerConfig log *zap.Logger } func (h *groupHandler) Setup(sarama.ConsumerGroupSession) error { return nil } func (h *groupHandler) Cleanup(sarama.ConsumerGroupSession) error { return nil } // ConsumeClaim 逐条处理:成功 Mark + 周期 Commit;失败跳过不提交; // 可选 pacing(每 PaceEvery 条成功消息歇 PaceSleep,存量回放防落库风暴)。 // WorkersPerPartition>1 时转并行路径(consumeParallel)。 func (h *groupHandler) ConsumeClaim(sess sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error { if h.cfg.WorkersPerPartition > 1 { return h.consumeParallel(sess, claim) } n := 0 paced := 0 pace := h.cfg.PaceEvery > 0 && h.cfg.PaceSleep > 0 for { select { case <-sess.Context().Done(): return nil case msg, ok := <-claim.Messages(): if !ok { return nil } if err := h.cfg.Handler(sess.Context(), msg); err != nil { // 不 Mark:offset 不前进,重平衡/重启后重新投递(at-least-once) h.log.Warn("kafka_consume_handler_failed", zap.String("topic", msg.Topic), zap.Int32("partition", msg.Partition), zap.Int64("offset", msg.Offset), zap.Error(err)) continue } sess.MarkMessage(msg, "") n++ if n >= h.cfg.CommitEveryN { sess.Commit() // 手动提交已 Mark 的 offset n = 0 } // Day58 pacing:以成功消息计数驱动(失败消息不歇,快速跳过毒丸), // 等待期可被会话取消即时打断(不阻塞优雅退出/重平衡)。 if pace { paced++ if paced >= h.cfg.PaceEvery { select { case <-time.After(h.cfg.PaceSleep): case <-sess.Context().Done(): return nil } paced = 0 } } } } } // consumeParallel 每分区 worker 池(Day 65):消息乱序并行处理,提交严格按 // offset 连续前缀推进——仅 Mark「自身与前驱均已完成」的消息,at-least-once // 与串行版等价: // - 失败消息不 Mark 但允许前缀越过(重试语义交 ConsumerGroup wrap 层, // 与串行版「失败 continue、后继 Mark 越过」一致); // - 会话结束/通道关闭时窗口内在途消息一律不 Mark,重平衡/重启后重投。 // // 背压:tasks 通道容量=workers,打满时取消息阻塞(worker 消化后自续)。 func (h *groupHandler) consumeParallel(sess sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error { workers := h.cfg.WorkersPerPartition type outcome struct { msg *sarama.ConsumerMessage // nil=在途占位(已取未完成) err error } tasks := make(chan *sarama.ConsumerMessage, workers) // 容量须 ≥ 2×workers+2(在途上限=tasks 缓冲+worker 手中各一):否则主循环 // 阻塞投 tasks 时无人消费 done,worker 全阻塞在 done<- 形成死锁环(单测实证)。 done := make(chan outcome, workers*2+2) var wg sync.WaitGroup for i := 0; i < workers; i++ { wg.Add(1) go func() { defer wg.Done() for m := range tasks { out := outcome{msg: m, err: h.cfg.Handler(sess.Context(), m)} select { case done <- out: case <-sess.Context().Done(): return } } }() } go func() { wg.Wait(); close(done) }() n, paced := 0, 0 pace := h.cfg.PaceEvery > 0 && h.cfg.PaceSleep > 0 next := int64(-1) // 待推进起始 offset(首条消息锚定) window := map[int64]outcome{} // offset→处理结果(占位/完成) // stop 关闭取数通道并等 worker 全部收尾(结果通道关闭),防 goroutine 泄漏。 stop := func() { close(tasks) for range done { /* 丢弃在途结果:会话已结束,Mark 无意义 */ } } // advance 推进连续完成前缀:成功 Mark+周期 Commit+可选 pacing;失败仅记日志越过。 // 返回 false=会话取消(pacing 等待被打断),调用方须立即退出。 advance := func() bool { for { v, exists := window[next] if !exists || v.msg == nil { return true } if v.err == nil { sess.MarkMessage(v.msg, "") n++ if n >= h.cfg.CommitEveryN { sess.Commit() n = 0 } if pace { paced++ if paced >= h.cfg.PaceEvery { select { case <-time.After(h.cfg.PaceSleep): case <-sess.Context().Done(): return false } paced = 0 } } } else { // 不 Mark:offset 不前进,重平衡/重启后重新投递(at-least-once) h.log.Warn("kafka_consume_handler_failed", zap.String("topic", v.msg.Topic), zap.Int32("partition", v.msg.Partition), zap.Int64("offset", v.msg.Offset), zap.Error(v.err)) } delete(window, next) next++ } } // pending pattern(Day65 死锁修复):投 tasks 阻塞期间仍须消费 done——若投递 // 用嵌套 select 独占等待,done 满后 worker 阻塞发送、不再取 tasks,与主循环 // 互锁(生产实证:16 分区 worker 卡 done<-、主循环卡 tasks<-,进程全静默)。 var pending *sarama.ConsumerMessage for { if pending == nil { select { case <-sess.Context().Done(): stop() return nil case msg, ok := <-claim.Messages(): if !ok { stop() return nil } if next < 0 { next = msg.Offset } window[msg.Offset] = outcome{} // 在途占位:阻挡前缀越过未完成消息 pending = msg case r, ok := <-done: if !ok { return nil // 仅 stop 后到达:worker 已全部收尾 } window[r.msg.Offset] = r if !advance() { return nil } } continue } select { case <-sess.Context().Done(): stop() return nil case tasks <- pending: pending = nil case r, ok := <-done: if !ok { return nil } window[r.msg.Offset] = r if !advance() { return nil } } } }