golang如何使用Asynq分布式任务队列_golang Asynq分布式任务队列使用详解-Golang-PHP中文网

Asynq 启动连不上 Redis 需检查地址、密码及连接池配置；handler panic 因类型名不一致或注册时机错误；幂等需任务 ID 加业务层唯一校验；本地开发推荐 Docker Redis 而非 mock；测试用 asynq.TestClient；CI 可用 miniredis。

golang如何使用asynq分布式任务队列_golang asynq分布式任务队列使用详解

Asynq 默认依赖 Redis 作为后端存储，启动 asynq.Server 时若报错 redis: connection refused 或超时，本质是客户端没连上 Redis 实例。不是 Asynq 本身有问题，而是连接配置或网络没对上。

检查 asynq.RedisClientOpt 中的 Addr 是否写成 "localhost:6379" —— Docker 容器内运行时应改用宿主机 IP（如 "172.17.0.1:6379"）或 Redis 服务名（K8s/Compose 场景）
密码必须显式传入 Password 字段，空字符串 "" 和 nil 行为不同：后者会跳过 AUTH，前者会发 AUTH "" 导致失败
加 ConnMaxIdleTime 和 ConnMaxLifetime 防止连接池复用僵死连接，尤其在 Redis 重启或中间件（如 Twemproxy）断连后

这个 panic 发生在调用 srv.Run() 后消费任务时，不是启动时报错。说明任务入队了，但 Asynq 运行时找不到对应 handler —— 常见于类型名拼写不一致或注册时机错误。

确保 srv.Mux().Handle("send_email", &EmailHandler{}) 中第一个参数（task type）和入队时 asynq.NewTask("send_email", payload) 的字符串完全一致，大小写敏感
Handler 结构体方法必须叫 ProcessTask，签名固定为 func(*asynq.Context, *asynq.Task) error，少一个星号或改名都会导致反射失败
不要在 goroutine 里注册 handler，比如 go func() { mux.Handle(...) }() —— 主流程可能已执行 Run()，注册失效

Asynq 默认提供 at-least-once 语义，网络分区或进程崩溃会导致重复执行。要实现 exactly-once 效果，得靠业务层幂等 + 任务配置协同。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

给任务加唯一 ID：asynq.NewTask("send_email", payload, asynq.TaskID("uid-123"))，配合 Redis SETNX 或数据库唯一索引做幂等判断
设置 RetryDelay 和 MaxRetry 控制重试节奏，避免短时间高频重试冲垮下游；MaxRetry: 0 表示不重试，适合纯通知类任务
避免在 ProcessTask 中直接修改共享状态（如全局 map），Asynq 可能并发执行同一 type 的多个 task，竞态风险高

Asynq 没有内置内存模式，硬切到 redis.UniversalClient 的 mock 实现容易漏掉 pipeline、事务等行为差异，不推荐。更稳妥的做法是轻量级 Redis 本地化。

用 docker run -d --name asynq-redis -p 6379:6379 redis:7-alpine 一行拉起，比自己写 fake client 更贴近真实
测试中需要断言任务是否入队？别 mock Redis，改用 asynq.TestClient：它返回一个内存版 Client，支持 .WaitForCompletion 和 .InspectPending，专为单元测试设计
CI 环境若不能跑 Docker，可用 github.com/alicebob/miniredis/v2 启一个 in-process Redis，注意它不支持 Lua 脚本 —— Asynq 的 zpopmin 等操作没问题，但自定义延迟队列逻辑会挂

Asynq 的配置项看似简单，但 QueueName、Concurrency、Timeout 这几个字段一旦设错，问题往往延迟暴露——比如任务卡住不报错，只在流量上来时突然积压。上线前务必用真实负载压测队列吞吐，别只看单任务日志。