Go Paho MQTT Go 怎样配置连接的遗嘱消息

我在做 MQTT 在线状态监控时，最容易把“遗嘱消息”误写成一次普通的 Publish。Paho MQTT Go 的正确入口是在创建客户端前给 ClientOptions 调用 SetWill，把主题、载荷、QoS 和 retained 一起交给连接配置；broker 在连接异常中断时，才按 MQTT 语义处理这条遗嘱。

官方地址：https://pkg.go.dev/github.com/eclipse/paho.mqtt.golang

最小配置就是 mqtt.NewClientOptions().SetWill(...)，并确保它发生在 NewClient 和 Connect 之前。正常退出要走 Disconnect，不要把遗嘱当成正常下线通知。

先判断遗嘱消息该放在哪个连接配置层

遗嘱描述的是“客户端失联后，broker 可以替客户端发布什么状态”，所以它属于连接建立时的参数，而不是连接成功后才补发的业务消息。Paho 文档把 SetWill(topic, payload, qos, retained) 放在 ClientOptions 上；需要二进制载荷时，使用对应的 SetBinaryWill。

我通常先把这四个参数写成一张小表，避免把状态语义混在一起：

在 Connect 前配置 SetWill

下面的代码把“设备离线”作为当前状态发布到状态主题。重点不是连接地址，而是 SetWill 位于 Connect 之前，并且连接 token 仍然要等待错误结果。

package main

import (
    "log"
    "time"

    mqtt "github.com/eclipse/paho.mqtt.golang"
)

func main() {
    opts := mqtt.NewClientOptions()
    opts.AddBroker("tcp://broker.example.com:1883")
    opts.SetClientID("sensor-gateway-01")

    // 连接建立前配置遗嘱，让 broker 知道异常断线后的状态主题和载荷。
    opts.SetWill("devices/sensor-gateway-01/state", "offline", 1, true)

    client := mqtt.NewClient(opts)
    token := client.Connect()
    // Connect 是异步 token；等待结果才能把连接失败纳入告警。
    if token.Wait() && token.Error() != nil {
        log.Fatalf("MQTT 连接失败: %v", token.Error())
    }

    // 业务运行期间保持进程存活；实际服务应由主循环或信号处理接管。
    time.Sleep(30 * time.Second)

    // 正常退出要显式断开，避免把一次主动下线误判为异常断线。
    client.Disconnect(250)
}

这里的 retained=true 让后来订阅状态主题的消费者可以读到 broker 保留的最近状态。若你的主题表达的是“发生过一次断线事件”，则不应机械开启 retained，而要让消费者按事件模型处理。

按状态主题选择 QoS 与 retained

我会先问一句：订阅者要的是“现在是否在线”，还是“刚刚发生过一次断线”？前者通常适合 retained 状态；后者更像事件流。QoS 只描述 MQTT 的传递等级，不能保证业务一定只处理一次，也不能替代去重和幂等。

如果载荷不是字符串，使用二进制接口能避免在客户端层面先做不必要的编码转换：

payload := []byte(`{"status":"offline","reason":"connection_lost"}`)

opts := mqtt.NewClientOptions()
opts.AddBroker("tcp://broker.example.com:1883")

// 二进制遗嘱适合已经序列化好的 JSON、协议帧或其他字节载荷。
opts.SetBinaryWill("devices/gateway-01/state", payload, 1, true)

// 连接前仍要把包含遗嘱的 options 交给客户端。
client := mqtt.NewClient(opts)

不要把真实密码、Token 或内部地址写进示例。生产环境应通过安全配置注入认证信息，并把状态主题的权限限制在需要订阅或发布的客户端范围内。

把异常断线与正常退出分开处理

排障时我会把告警分成两条线：broker 是否观察到异常断开，以及应用自身是否收到连接丢失回调。遗嘱由 broker 负责发布，连接丢失回调由客户端负责记录、重连或拉起本地处置；两者不是同一条消息链路。

正常退出应先完成业务收尾，再调用 Disconnect。如果连接尚未建立，或测试场景需要撤销已经配置但尚未使用的遗嘱，可以调用 UnsetWill；它是配置回滚，不是给 broker 发布“在线”消息。

opts := mqtt.NewClientOptions()
opts.AddBroker("tcp://broker.example.com:1883")

// 回调只记录客户端侧的断线原因，不代替 broker 的遗嘱消息。
opts.SetConnectionLostHandler(func(client mqtt.Client, err error) {
    log.Printf("MQTT 连接丢失: %v", err)
})

// 发现本次连接不应携带遗嘱时，连接前可以回滚这项配置。
opts.SetWill("devices/gateway-01/state", "offline", 1, true)
opts.UnsetWill()

client := mqtt.NewClient(opts)

上线前的告警确认与复盘清单

出现“设备离线”告警时，先看 broker 侧是否收到了客户端异常断开，再看订阅者是否因为 retained 读到了旧状态，最后核对客户端日志中的连接丢失原因。不要只凭一次状态消息判断网络、进程和 broker 哪一层出了问题。

• 触发信号：客户端进程被杀、网络中断、KeepAlive 超时，还是主动发布了业务下线事件。
• 快速判断：遗嘱主题、客户端 ID、QoS、retained 设置与订阅者预期是否一致。
• 回滚路径：先用 UnsetWill 或关闭状态主题消费，避免错误载荷继续扩大影响；不要重复发布不确定的在线状态。
• 告警确认：对照 broker 日志、客户端连接丢失回调和订阅者收到的消息，确认是否同一客户端 ID。
• 复盘项：是否需要唯一 ClientID、是否需要保留状态、是否把事件与当前状态误用同一主题。

常见问题

SetWill 应该在 NewClient 后调用吗？

稳妥写法是在 NewClient 前把选项配置完整，再创建客户端并调用 Connect。这样连接使用的就是已经包含遗嘱的 ClientOptions。

正常调用 Disconnect 会发布遗嘱吗？

遗嘱用于异常断开语义。正常下线应调用 Disconnect，并由业务另外发布明确的在线状态或离线事件；不要把遗嘱当作正常退出的通知接口。

为什么 retained 状态看起来像“重复离线”？

新订阅者可能先收到 broker 保留的最近状态，随后又收到实时消息。消费者需要区分“进入订阅时的当前状态”和“连接期间发生的新事件”，必要时在载荷中增加时间或状态版本。