Go语言machinery任务队列使用教程

本文深入剖析了Go语言中使用machinery任务队列时最易踩坑的核心要点，直击函数签名必须严格为`func(interface{}) error`、broker与result_backend配置需协议完整且DB隔离、参数类型仅限基础类型名、ETA必须是Unix时间戳等关键约束，揭示其“静默失败”的设计本质——注册错误、配置偏差或序列化不兼容均不会报错，而是导致任务丢失或worker卡在“waiting for tasks”，堪称一场对细节精度的严苛考验。

machinery 不是开箱即用的库，注册错签名、配错 broker 和 result_backend、参数类型不兼容，三者任一出问题，任务都会静默丢失或 worker 卡在 “waiting for tasks” —— 这不是 bug，是设计使然。

注册任务函数必须是 func(interface{}) error，不能带指针接收器

machinery 只认包级纯函数，且签名必须严格匹配 func(interface{}) error。返回值只能是 error，不能多一个 int，也不能少；interface{} 是唯一允许的参数类型，不能写成 func(*MyService) error 或 func(a int, b string) error。

• ✅ 正确示例：func SendEmail(args interface{}) error { ... }，内部再手动类型断言
• ❌ 错误示例：func (s *Mailer) Send() error —— 方法绑定不被支持，RegisterTask 会 panic
• ⚠️ 常见陷阱：结构体字段没加 json: tag，传参后 worker 收到空值；time.Time 直接塞进 interface{} 会导致 JSON 序列化失败，建议转成 int64 或 RFC3339 字符串

broker 和 result_backend 必须协议完整、地址分离、DB 隔离

配置项写错不会报错，但 worker 启动后根本收不到任务。最典型的现象是日志只显示 waiting for tasks，无任何连接失败提示。

• ✅ 协议必须显式写出：redis://123456@localhost:6379 ✅，localhost:6379 ❌（machinery 不自动补 redis://）
• ✅ Redis 作 broker 时，result_backend 别用同一实例的同一 DB：比如 broker 用 redis://.../0，backend 就该用 redis://.../1 或换 memcache://，否则并发写冲突导致任务丢弃
• ✅ 启动前手动验证连通性：redis-cli -u redis://localhost:6379 ping 或 curl -I amqp://guest:guest@localhost:5672

发送任务时 Args 类型字符串必须是 Go 基础类型名

SendTask 不校验参数类型是否可序列化，也不检查任务是否已注册——发出去就“成功”，但 worker 根本不会执行。问题出在 tasks.Arg 的 Type 字段。

• ✅ 正确写法：Args: []tasks.Arg{{Type: "int", Value: 42}}、{Type: "string", Value: "hello"}
• ❌ 错误写法：{Type: "[]byte"}、{Type: "MyInt"（自定义别名）、{Type: "map[string]interface{}"}（JSON 不支持 interface{} 键）
• ⚠️ 注意：nil 切片会被序列化为 null，worker 端需主动判空；嵌套过深的 struct 可能触发 JSON 递归限制，建议扁平化传参

延迟任务靠 ETA 时间戳，不是相对秒数

设置延迟任务时，ETA 字段必须是 Unix 时间戳（秒级整数），不是“5 秒后”。填错会导致任务立刻执行（时间戳过小）或永远不触发（时间戳为 0 或负数）。

• ✅ 正确计算：time.Now().Add(5 * time.Second).Unix()
• ❌ 错误写法：ETA: 5（这会被当成 1970-01-01 00:00:05 UTC，早就过了）
• ⚠️ 重试依赖 RetryCount + RetryTimeout，二者都得显式设；默认不重试，且重试状态不持久化——worker 重启后未完成的重试直接消失

真正难的不是写几行注册和发送代码，而是所有环节都得对齐：函数签名、JSON 序列化规则、broker/backend 地址格式、时间戳语义。任何一个链路断掉，machinery 都不会提醒你——它只会安静地丢掉任务。

到这里，我们也就讲完了《Go语言machinery任务队列使用教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！