---
tags:
  - MQ
create time: 2026-05-24 19:52
---

# MQ 客户端 SDK 最佳实践

## 概述

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

## 正文

### SDK 设计原则

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

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

```go
// 抽象接口设计
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）

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

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

核心代码：

```go
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）**，而不是无限重试或丢弃。同时触发告警通知运维人员。

```go
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 等上下文信息。

```go
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 应该默认开启自动重试吗？重试次数和间隔如何确定？提示：考虑幂等性和消费者的处理能力。

## 关联笔记

- [[47-MQ-与微服务]]
- [[49-MQ-客户端连接管理]]
- [[50-MQ-设计与实现]]