Gin中NSQ生产者必须全局复用，禁在handler中新建；Consumer Handler需同步执行、禁手动启goroutine；msg.Finish/Requeue/Touch须按业务成败显式调用，defer无条件Finish会导致消息丢失。
Gin 处理 HTTP 请求时直接调用 NSQ 生产者发消息，只要 Producer 复用得当、ACK 语义清晰、Consumer 并发可控，就能稳定解耦——但错在任意一环，比如每次请求 new Producer 或 defer msg.Finish()，线上就会丢消息或 OOM。
nsq.Producer 必须全局复用，别在 Gin handler 里 new
常见错误是把 nsq.NewProducer 写进 Gin 的 POST /order handler 里，每单请求建一个 Producer。它内部持 TCP 连接和发送缓冲区，短时间内大量新建会导致 too many open files，nsqd 拒绝新连接甚至夯住。
-
nsq.Producer应作为服务全局变量初始化一次，在main()或依赖注入容器中创建并调用p.Connect() - 务必启动 goroutine 监听
p.Err()，捕获io: read/write timeout等错误，否则网络抖动后 Producer 会静默卡死 - 异步发布用
PublishAsync()时，回调函数里禁止阻塞（如 sleep、DB 查询），否则压垮 Producer 的内部队列 - 若用
nsqlookupd做服务发现，初始化 Producer 时需传cfg.LookupAddresses = []string{"127.0.0.1:4161"}（注意是 HTTP 端口 4161，不是 TCP 的 4160）
Consumer 的 HandlerFunc 别自己起 goroutine
NSQ 客户端已内置并发模型，consumer.ChangeMaxInFlight(4) 控制的是“同时处理的消息数”，不是“并发 goroutine 数”。在 HandleMessage 里再套一层 go func() { ... }() 是典型反模式，会导致 goroutine 泛滥、内存暴涨，压测时直接 OOM。
- 业务逻辑必须同步执行，让 HandlerFunc 自然返回，由 NSQ 客户端决定何时调用
msg.Finish()或重试 - 如需异步调外部 HTTP，用带超时的
http.Client.Do()，且必须显式判断 error 后决定msg.Requeue()或msg.Finish() -
consumer.Stop()和consumer.WaitStopped()必须在进程退出前调用，否则未 ACK 的消息会丢失 - 禁用默认日志：
consumer.SetLogger(nil, nsq.LogLevelFatal)，高频场景下默认日志吞吐量远超业务本身
msg.Finish() / Requeue() / Touch() 的实际触发时机很关键
NSQ 不是“发完就完”，所有可靠性都靠这三者显式控制。很多故障源于在 defer 里无条件 msg.Finish()，结果 panic 或 error 后仍标记成功，消息永久消失。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
-
msg.Finish()只应在业务逻辑彻底成功后调用；一旦调用，消息从队列彻底移除 -
msg.Requeue(0)用于临时失败（如 DB 连接超时），但反复重试需自己维护重试计数，否则消息卡在 channel 里不动 -
msg.Touch()仅在明确需要 >60s 处理时用（如上传大文件），滥用会拖慢整体消费进度，且需配合手动msg.Finish()或msg.Requeue() - 绝对不要在
defer中写msg.Finish()；正确写法是：处理完、无 error →msg.Finish()；有 error 且可重试 →msg.Requeue(2 * time.Second)；不可重试 →msg.Finish()（或转存 DLQ）
Gin + NSQ 联调时最常被忽略的三件事
本地跑通不等于线上可用。三个点没验过，上线后基本要救火。
- 检查
nsqadmin页面 http://127.0.0.1:4171 是否能列出 topic 和 channel，确认 Producer 发的消息真进了队列 - Consumer 启动日志里有没有
CONNECTED，有没有报failed to connect to nsqlookupd—— 很多连不上是因为传了4160（TCP）而非4161（HTTP） - Channel 名必须一致且不能随意改：改名后旧 Channel 里的积压消息不会自动迁移到新 Channel，测试时清空旧 Channel 再验证
真正难的不是写几行 Publish() 或 HandleMessage()，而是把连接生命周期、并发控制、ACK 语义、重试边界全串起来——漏掉任意一个，系统就在高负载下悄悄失联或丢消息。
