Go语言asynq任务队列实战教程

本文深入解析了Go语言中asynq任务队列在实际开发中最常遇到的四大痛点：Redis连接失败（源于Addr不可达、密码未显式配置或版本不兼容）、任务不执行（因Type不匹配或Handler签名错误）、任务重复执行（由“至少一次”语义与非幂等处理引发）以及本地调试困难，并给出了精准、可落地的排查路径和最佳实践——从CLI快速查看pending任务，到强制幂等设计，再到理解重试机制与底层Redis行为的耦合关系，帮你避开那些隐蔽却致命的“默认陷阱”。

asynq.Client 初始化失败：连接不上 Redis 怎么办

asynq 本质是基于 Redis 的任务队列，asynq.NewClient 失败，90% 是 Redis 连接配置不对。别急着查任务逻辑，先确认底层通不通。

• asynq.RedisClientOpt{Addr: "localhost:6379"} 中的 Addr 必须可连——Docker 启动的 Redis 默认不监听 localhost（容器内是 redis 或 host.docker.internal）
• 密码没配？加 Password: os.Getenv("REDIS_PASSWORD")，空密码也得显式写 Password: ""，否则 asynq 会默认发 AUTH 命令导致连接被拒
• Redis 版本低于 6.0？asynq v0.25+ 默认启用 CLIENT ID 和 XPENDING，老版本 Redis 会报 ERR unknown command —— 降级到 asynq v0.24 或升级 Redis

任务没被执行：Server 启动了但 Handler 不触发

asynq.Server 启动后静默，不是“跑得快”，而是注册的 handler 根本没匹配上任务类型。关键在 asynq.Task{Type: "send_email", Payload: ...} 的 Type 字符串必须和 srv.Mux.HandleFunc("send_email", handler) 完全一致，包括大小写、下划线、空格。

• 常见错误：任务用 "SendEmail"，handler 注册的是 "send_email" → 不匹配，任务进队列后永远 pending
• Handler 函数签名必须是 func(ctx context.Context, t *asynq.Task) error，多一个参数或少一个 error 返回，运行时 panic 且无日志（默认 logger 级别是 warn）
• 没调 srv.Run()？只调 srv.Start() 是不行的，后者只是启动 goroutine，真正消费靠 Run

任务重复执行：同一个 job 被 handle 了两次

asynq 默认不保证“恰好一次”，它靠 Redis 的原子操作 + 超时机制实现“至少一次”。重复执行不是 bug，是设计使然；但如果你的 handler 不幂等，就会出问题。

• 根本原因：handler 执行时间超过 asynq.ServerOption{RetryDelay: 10 * time.Second} 设置的超时（默认 10s），asynq 认为失败，重入队列
• 解决方向不是调长超时，而是让 handler 快速返回 + 幂等：用 Redis SETNX 或数据库唯一约束标记 job ID 已处理
• 别依赖 t.ID() 做去重键——重试时 ID 不变，但 t.RetryCount() 会变，建议组合使用："job_processed:" + t.ID() + ":" + strconv.Itoa(t.RetryCount())

本地开发调试：怎么看到队列里卡了哪些 job

asynq 提供 Web UI，但本地快速排查不用开浏览器——直接用 asynqadm CLI 或 Redis 命令看原始数据更准。

• 装 CLI：go install github.com/hibiken/asynq/cmd/asynqadm@latest，然后 asynqadm -v -u redis://localhost:6379 list tasks default 查 pending job
• 想看某个 job 内容？asynqadm -v -u redis://localhost:6379 show task job_id，注意 job_id 是 base64 编码的，别手动解码，CLI 会自动处理
• Redis 命令行也能查：LRANGE asynq:default:pending 0 -1 拿 ID 列表，再 HGETALL asynq:task:job_id 看 payload —— 但 payload 是 JSON，中文可能乱码，优先用 CLI

asynq 的坑不在语法，而在 Redis 底层行为和重试语义的耦合。比如你改了 handler 逻辑，但队列里还有旧 job 在 pending，它们照常执行旧代码——这种“看不见的延迟”最容易被忽略。

以上就是《Go语言asynq任务队列实战教程》的详细内容，更多关于的资料请关注golang学习网公众号！