RabbitMQ连接需全局单例复用，channel按需创建并及时关闭；必须监听NotifyClose实现自动重连，Publish失败需检查channel状态；任务结构体须规范JSON序列化；消费者必须手动Ack并绑定context超时控制。
直接用 Go 原生 amqp 客户端集成 RabbitMQ 就能跑通分布式任务调度，不需要框架“套壳”——但如果你用了 go-zero 或 Gin 这类框架，关键不是“能不能集成”，而是怎么把连接生命周期、错误重连、任务反序列化和上下文取消这几个点对齐业务真实节奏。
amqp.Dial 之后必须手动管理连接和 channel 的复用
RabbitMQ 连接（*amqp.Connection）是重量级资源，不能每次发任务都 amqp.Dial + ch.Close()。常见错误是：在 HTTP handler 里临时建 channel 发消息，结果高并发时触发 TCP 端口耗尽或 RabbitMQ 连接数超限。
- 连接应全局单例，启动时初始化，用
sync.Once保证； - channel 要池化或按业务域隔离（比如“调度命令 channel”和“状态上报 channel”不共用一个）；
- 必须监听
conn.NotifyClose()并触发自动重连，否则网络抖动后整个调度链就静默中断； -
ch.Publish失败时不要只 log，要检查是否因 channel 已关闭而 panic —— 这类错误在压力测试中才暴露。
任务结构体的 JSON 序列化必须带明确字段标签与默认值处理
Go 的 json.Marshal 对空字段、零值、嵌套 map 的行为容易引发消费者解析失败。比如 params map[string]interface{} 在 producer 侧传了 nil，consumer 侧用 json.Unmarshal 解到 struct 会 panic，而不是静默跳过。
- 定义 task struct 时所有字段加
json:"field_name,omitempty"，避免意外透出零值； - 关键字段（如
ID、Type）不设omitempty，并在 Unmarshal 后立刻校验非空； - 避免直接用
interface{}接收 params，改用具体子类型（如SendEmailTaskParams），靠消息头ContentType或Type字段路由； - RabbitMQ 的
deliveryMode: amqp.Persistent必须开启，否则 broker 重启后队列里未消费的消息全丢。
消费者端必须用 ch.Consume + 手动 Ack，且 context 要穿透到执行层
很多人写 consumer 时用 autoAck: true 图省事，结果任务执行到一半 panic，消息却已被 RabbitMQ 删除——这等于永久丢失任务。更隐蔽的问题是：goroutine 没绑定 context.Context，超时后无法终止正在运行的 HTTP 请求或数据库事务。
立即学习“go语言免费学习笔记（深入）”；
-
ch.Consume的autoAck必须为false； - 每个
delivery启动 goroutine 时，用context.WithTimeout(parentCtx, 30*time.Second)包一层； - 执行完逻辑后，先
d.Ack(false)，再 return；若出错，调d.Nack(false, true)让消息重回队首（注意requeue=true）； - 别在 defer 里 Ack —— defer 只在函数 return 时执行，而 panic 会跳过它。
go-zero 配置 rabbitmq 时 virtualhost 和 queue 名称必须显式声明
go-zero 的 message 模块默认 virtualhost 是 /，但生产环境几乎都改过。如果配置里漏写 virtualhost，连接看似成功，实际 publish 时会报 ChannelError: NOT_FOUND - no queue 'xxx' in vhost '/'，而日志里只显示 “publish failed”，根本看不出是 vhost 错了。
- 确认 RabbitMQ 中已创建对应
vhost，并给用户授了权限（sudo rabbitmqctl set_permissions -p your_vhost user ".*" ".*" ".*"）； -
queue名称不能含/或空格，go-zero 不做 trim； - go-zero 的
Push方法内部不返回 error，失败时只打 warn 日志——务必打开logx.DisableStat()并观察 warn 级别输出； - 如果要用延迟任务，RabbitMQ 原生不支持，得靠死信队列+TTL，go-zero 的
PushDelay是假的，底层仍是立即投递。
最容易被忽略的是：RabbitMQ 的 connection/channel 关闭不是原子操作，conn.Close() 返回后，正在写的 channel 可能还在发包，此时强行 kill 进程会导致部分消息卡在 socket buffer 里发不出去。上线前一定要压测 shutdown 流程，看有没有消息“发了一半就消失”。
