MQ 客户端 SDK 最佳实践

概述

一个好的 MQ SDK 能让开发者专注于业务逻辑，而不是陷入连接管理、重试策略、序列化等底层细节。本文从 SDK 设计原则、连接管理、优雅关闭、序列化策略、错误处理、可观测性等维度，介绍生产级 MQ SDK 的设计要点，并给出完整的 Go 封装示例。

正文

SDK 设计原则

一个优秀的 MQ 客户端 SDK 应该遵循四个原则：

抽象接口：隐藏底层 MQ 实现细节，业务代码不直接依赖 Kafka/RocketMQ/RabbitMQ 的原生 API。这样切换 MQ 产品时只改 SDK 实现，不改业务代码。
可配置性：超时、重试次数、批次大小等参数应该可配置，而不是硬编码。
重试与容错：网络抖动、Broker 短暂不可用时自动重试，而不是让业务代码处理。
可观测性：内置 TraceID 注入、Metrics 埋点、结构化日志，方便排查问题。

// 抽象接口设计
type MQProducer interface {
    Send(ctx context.Context, topic string, message *Message) error
    SendBatch(ctx context.Context, topic string, messages []*Message) error
    Close() error
}

type MQConsumer interface {
    Subscribe(topic string, handler func(ctx context.Context, msg *Message) error) error
    Close() error
}

type Message struct {
    Key       string
    Value     []byte
    Headers   map[string]string
    Timestamp time.Time
}

连接管理

MQ 客户端通常维护长连接而非短连接。建立连接的开销（TCP 三次握手 + MQ 协议握手）很大，频繁创建销毁会严重影响性能。

连接池设计要点：

初始连接数和最大连接数可配置。
连接空闲超时后自动回收。
健康检查：定期发送心跳探测连接是否存活。
自动重连：检测到连接断开后，后台自动重建连接。

优雅关闭（Graceful Shutdown）

优雅关闭是生产环境最容易被忽略、最容易出问题的环节。关闭顺序至关重要：

graph LR
    A["收到 SIGTERM"] --> B["停止接受新消息"]
    B --> C["等待当前消息处理完成"]
    C --> D["提交 Offset - 消费者"]
    D --> E["刷新缓冲区 - 生产者"]
    E --> F["关闭连接"]

核心代码：

type Client struct {
    producer  MQProducer
    consumer  MQConsumer
    shutdown  chan struct{}
    wg        sync.WaitGroup
}

func (c *Client) GracefulShutdown(ctx context.Context) error {
    close(c.shutdown) // 1. 通知所有 goroutine 停止接受新任务

    // 2. 等待所有进行中的任务完成（带超时）
    done := make(chan struct{})
    go func() {
        c.wg.Wait()
        close(done)
    }()

    select {
    case <-done:
        // 正常完成
    case <-ctx.Done():
        // 超时，强制关闭
        log.Warn("graceful shutdown timeout, forcing close")
    }

    // 3. 关闭连接
    c.producer.Close()
    c.consumer.Close()
    return nil
}

序列化策略

消息体的序列化方式直接影响性能和可调试性：

方式	优点	缺点	适用场景
JSON	人类可读、调试方便	体积大、序列化慢	业务消息、日志
Protobuf	体积小、速度快	需要预定义 Schema	高性能内部通信
Avro	Schema 演进支持好	生态相对小	数据湖、大数据场景
MessagePack	类 JSON 但更紧凑	生态不如 JSON	性能敏感 + 跨语言

错误处理

SDK 必须区分可重试错误和不可重试错误：

可重试：网络超时、Broker 暂时不可用、限流（429）。这些错误过一会儿重试可能就成功了。
不可重试：消息格式错误、Topic 不存在、权限不足。重试多少次都不会成功。

不可重试的消息应该进入死信队列（Dead Letter Queue），而不是无限重试或丢弃。同时触发告警通知运维人员。

func (c *Client) SendWithRetry(ctx context.Context, topic string, msg *Message) error {
    for i := 0; i <= c.maxRetries; i++ {
        err := c.producer.Send(ctx, topic, msg)
        if err == nil {
            return nil
        }
        if !isRetryable(err) {
            c.sendToDLQ(topic, msg, err) // 不可重试，进死信
            c.alertManager.Notify("unrecoverable mq error", err)
            return err
        }
        // 指数退避
        time.Sleep(c.backoff(i))
    }
    c.sendToDLQ(topic, msg, errors.New("max retries exceeded"))
    return errors.New("send failed after retries")
}

可观测性集成

生产级 SDK 必须内置可观测性：

TraceID 注入：在消息 Headers 中注入 TraceID，实现跨服务链路追踪。
Metrics 埋点：发送成功率、消费延迟、队列堆积量等关键指标。
结构化日志：JSON 格式日志，包含 Topic、Partition、Offset 等上下文信息。

func (c *Client) Send(ctx context.Context, topic string, msg *Message) error {
    start := time.Now()

    // 注入 TraceID
    if span := trace.SpanFromContext(ctx); span.SpanContext().IsValid() {
        msg.Headers["trace-id"] = span.SpanContext().TraceID().String()
    }

    err := c.producer.Send(ctx, topic, msg)

    // Metrics 埋点
    duration := time.Since(start)
    c.metrics.Histogram("mq.send.duration").Observe(duration.Seconds())
    c.metrics.Counter("mq.send.total").Inc()
    if err != nil {
        c.metrics.Counter("mq.send.error").Inc()
    }

    // 结构化日志
    c.logger.Info("message sent",
        zap.String("topic", topic),
        zap.String("key", msg.Key),
        zap.Duration("latency", duration),
        zap.Error(err),
    )
    return err
}

[!question] SDK 应该默认开启自动重试吗？重试次数和间隔如何确定？提示：考虑幂等性和消费者的处理能力。

5.9 KiB Raw Blame History Unescape Escape