如何在 Golang 框架中集成异步任务队列 Machinery-Golang-PHP中文网

必须显式初始化配置、注册任务、启动worker，三者缺一不可，否则worker卡在“waiting for tasks”且不报错；config.newfromyaml需手动调用且路径/格式须正确，broker与result_backend协议必须显式写出、db应隔离，任务签名严格限定为func(interface{}) error，args.type仅支持基础类型名，eta须为unix时间戳，retrycount与retrytimeout须同时设置。

如何在 golang 框架中集成异步任务队列 machinery

必须显式初始化配置、注册任务、启动 worker，三者缺一不可；否则 worker 会卡在 “waiting for tasks” 且不报错。

config.NewFromYaml 必须手动调用且路径/格式不能错

machinery 不会自动读 machinery.yaml，必须在 server.NewServer 前调用 config.NewFromYaml("./conf/machinery.yaml")。常见静默失败点：

路径写错（如工作目录不是 binary 所在目录，"machinery.yaml" 就找不到）
YAML 缩进不规范或字段名拼错：broker 写成 broker_url 或 result_backend 少下划线，字段就为空
协议缺失：redis://123456@localhost:6379/0 ✅，localhost:6379 ❌（machinery 不补协议）
default_queue 含空格或斜杠（如 "my queue" 或 "task/v1"），AMQP 模式直接报 AMQP queue name invalid

任务函数签名必须是 func(interface{}) error

注册时任何偏差都会导致 server.RegisterTask panic，错误只提示 invalid task signature，不指明位置：

Redis Skill - 高性能缓存管理

Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。

下载

参数只能是 interface{}，不能是 string、struct{} 或带接收器的方法（如 (s *Svc) Do()）
返回值只能是 error，不能多一个 int，也不能是 (string, error)
worker 端需手动类型断言：args := payload.(map[string]interface{})，建议加 ok 判断防 panic
结构体字段必须加 json: tag，否则序列化后字段为空

发送任务时 Args 必须 JSON 可序列化且 Type 字符串要准确

SendTaskWithContext 不校验参数合法性，传错就静默丢弃——你发了，worker 收不到：

time.Time 不能直传，会 panic；改用 Unix() 或 Format("2006-01-02T15:04:05Z")
[]int{1,2,3} 要先转成 []interface{}，否则序列化为空或 panic
tasks.Arg.Type 必须是 Go 基础类型名字符串："string"、"int"、"float64" ✅，"[]byte"、"MyInt"、"map[string]interface{}" ❌
nil 切片传过去变成 null，worker 端不能直接遍历，得先判空

延迟和重试必须靠 ETA / RetryCount 显式设置

machinery 默认不延迟、不重试，所有“看似该生效却没反应”的行为，基本都是这两个字段漏设：

ETA 是 Unix 时间戳（秒级整数），不是 duration：time.Now().Add(5 * time.Minute).Unix() ✅，30 ❌（会被当 1970 年时间戳）
RetryCount 和 RetryTimeout 必须同时设，缺一不可；默认都是 0，意味着哪怕 panic 也只执行一次
重试状态不持久化：worker 重启后，正在进行的重试就丢失——machinery 只依赖 broker 存活，不存重试上下文
Redis 作 broker 和 result_backend 时，别共用同一 DB（如都用 /0），建议 broker 用 DB 0，result_backend 用 DB 1，否则并发写可能丢结果