Golang MQTT客户端必须显式调用token.WaitTimeout()确认连接就绪、订阅时传非nil handler、区分QoS语义、显式调用Disconnect()，否则90%的消息收发问题将出现。
直接用 eclipse/paho.mqtt.golang 就能跑通基础通信，但不处理 token.Wait()、nil handler、QoS 语义和连接生命周期，90% 的“消息收不到”“发不出”问题都会出现。
connect() 后必须显式等待 token 完成
MQTT 连接是异步的，client.Connect() 立即返回一个 token，不代表已连上 Broker。跳过等待就发消息或订阅，轻则静默失败，重则 panic：panic: client is not connected。
-
token.Wait()是阻塞等待，适合简单脚本；生产环境务必用token.WaitTimeout(5 * time.Second)防卡死 - 检查不能只看
token.Error() != nil，还要确认token.WaitTimeout()返回true，否则可能是超时而非失败 - 配合
opts.SetAutoReconnect(true)和opts.OnConnectionLost才算完整容错，单纯靠Wait不解决断线重连
Subscribe 必须传非 nil 的 MessageHandler
client.Subscribe("sensor/temp", 1, nil) 看似合法，实际等于“订了但不看消息”——库收到消息后直接丢弃，不会报错也不会 log。
- handler 函数签名必须是
func(client MQTT.Client, msg MQTT.Message)，哪怕只做fmt.Println(string(msg.Payload())) - handler 内部别做耗时操作（如 DB 写入、HTTP 调用），否则阻塞整个 MQTT 事件循环；应把
msg推进一个chan MQTT.Message，由独立 goroutine 消费 - 循环订阅多个 topic 时，避免闭包捕获循环变量：
for _, t := range topics { client.Subscribe(t, 1, func(...) {...}) }中的t会被所有 handler 共享；应写成topic := t; client.Subscribe(topic, ...)
QoS 0 不等于“不可靠”，但行为依赖 Broker 配置
client.Publish("cmd/led", 0, false, []byte("on")) 发出去后没回音？不是 Go 代码问题，而是 QoS 0 本身不保证送达，且受 Broker clean session 和 retain 设置影响。
立即学习“go语言免费学习笔记（深入）”；
- 若订阅者晚于发布者上线，且 Broker 启用了
clean_session=true（默认），QoS 0 消息就真的消失了——它不存、不转发、不重试 - 测试阶段先用公共 Broker（如
tcp://broker.hivemq.com:1883）排除本地配置干扰；生产环境必须确认 EMQX/Mosquitto 的allow_anonymous、max_connections、max_qos参数允许你用的 QoS 等级 - 业务关键消息别硬扛 QoS 0：要么升到 QoS 1（Broker 必须支持 PUBACK）、要么在应用层加 ACK 机制（例如发布后监听
ack/cmd/led/{clientID}主题）
Disconnect 必须显式调用，不能 defer
defer client.Disconnect(250) 在 main 函数末尾看似稳妥，实则无效：Go 程序退出时，goroutine 可能已被强制终止，Disconnect() 来不及发 FIN 包，Broker 仍认为客户端在线，导致后续连接因 ClientID 冲突被拒。
- 应在明确退出前调用
client.Disconnect(250)，并等待完成：client.Disconnect(250); time.Sleep(100 * time.Millisecond) - 若程序需长期运行（如服务进程），根本不需要主动 Disconnect；靠 TCP Keepalive 和 Broker 的 idle timeout 自动清理更可靠
- 注意
Disconnect()参数是超时毫秒数，不是“等待时间”——设太小（如 10）可能断连不干净；设太大（如 5000）又拖慢退出
真正难的不是连上 MQTT，而是让每条消息在弱网、重启、Broker 切换等真实物联网场景下，按预期到达或明确失败。Context 控制超时、channel 解耦 handler、重试策略兜底——这些不是锦上添花，是默认就得写的部分。
