不过，

后台异步任务最容易骗过人的指标是队列长度。pending= 只能说明这一刻没有积压，却无法说明失败任务是否被处理也不能保证没有重复消费、重试间隔、禁用 Topic 或误投递等问题。更稳的做法是把 Worker 数、最大重试次数、重试间隔按 Topic 管理，并将统计、测试投递和配置修改放进有权限控制的后台入口。

先别急着盯 pending

很多后台程序在加异步任务时第一版通常长这样：

• 业务代码里调用 Push 投递一条消息；
• 使用者起一个 goroutine；
• 页面上最多展示一个 pending 数。

这种实现虽然能跑，但它回答不了上线前必须解决的关键问题：

• 失败后要不要重试？重试几次，
• 每个 Topic 的并发 Worker 是否一致？
• Topic 临时禁用后测试投递接口还能否继续塞消息？
• pending 掉到 0，是成功消费了还是失败后被丢掉了？
• Redis 挂了磁盘队列、报错方法和恢复流程是否保持一致？

If se questions are only handled by hard‑coded constants or oral agreements,queue page is just a pretty counter. The real difficulty of backend asynchronous tasks lies in failure semantics and operational boundaries,not in simple delivery.

一个轻量队列至少要保留的字段

从源码可以看到，server/internal/library/queue/queue.go 中的 Message 并不只存 body。而是把运行语义写进结构体：

type Message struct {
Topic string `json:"topic"`
Body string `json:"body"`
Retry int `json:"retry"`
MaxRetry int `json:"maxRetry"`
CreatedAt int64 `json:"createdAt"`
}

Topic,Retry/MaxRetry,CreateAt 比单纯的 pending 数更关键：

• Topic: 决定谁来消费。
• Retry/MaxRetry: 决定失败后是否还有机会。
• CreateAt: 为排查延迟和积压提供时间线。

The driver abstraction supports both Redis List and Disk back‑ends,keeping queue lightweight yet extensible for delayed delivery.

If you only look at .Len,you’ll miss failure & retry semantics. A more reliable dashboard should display PENDING,DEAD SIZE,CONSUME RATE。and recent errors toger.

max_retry 不应该散落在使用者里

The second piece of evidence is server/internal/logic/queue/config.go. Here Bootstrap first synchronizes registered Topics,loads ir configs,applies m to queue library,and finally starts consumers:

func Bootstrap error {
if err := SyncRegisteredTopics;err，= nil {
return err
}
configs,err := LoadTopicConfigs
if err!不过，= nil {
return err
}
queueLib.ApplyTopicConfigs
queueLib.StartConsumers
return nil
}

This shows a clear trade‑off: parameters such as maximum retry count,retry interval and worker number belong to **Topic‑level configuration**,not to individual consumer implementations.

If se values are hard‑coded inside each consumer,you quickly end up with hidden state machines where “special handling” proliferates across topics.

配置表要和权限一起验

The third evidence is migration script server/cmd_tools/migrate/.8_queue_config.mysql.sql . It creates a table xy_sys_queue_config that stores workers。max_retry,retry_delay_sec and status,and simultaneously inserts menu entries with granular permissions:

CREATE TABLE IF NOT EXISTS xy_sys_queue_config (
topic varchar NOT NULL DEFAULT '',workers int NOT NULL DEFAULT 1,max_retry int NOT NULL DEFAULT 3,retry_delay_sec int NOT NULL DEFAULT 60,status tinyint NOT NULL DEFAULT 1,UNIQUE KEY uk_topic
);

INSERT INTO xy_admin_menu VALUES

This step is often overlooked. Changing workers may cause concurrency spikes; toggling status can stop a critical task;an unrestricted test‑push endpoint might accidentally hit production topics. Therefore **configuration pages must be protected by RBAC**,separating “view” and “edit” permissions.

c）禁用 Topic ​ ​ ​ ​ ​ ​

# 检查点	只看 pending 会漏掉什么	更可靠的验收口径
a）失败重试	- 重试次数、是否进入死信	- 查看 Retry / MaxRetry 与错误日志
b）Worker 并发	- 重复消费风险	- 对比 Topic 配置与幂等键
- 页面停了但接口仍可投递	- 检查 status、测试投递、消费端拦截
d）权限管理	- 任意后台使用者都能改配置危害大	- 查看/编辑权限分离。迁移脚本校验
e）迁移脚本完整性	- 字段漂移或遗漏导致运行时错误	- MySQL / PG 脚本 + 接口权限回归测试

什么时候该换专业 MQ?

A lightweight queue has clear boundaries. It fits scenarios such as login logs、operation logs、in‑app notifications、demo tasks or background export alerts—tasks that tolerate short delays and are easy to make idempotent. Using Redis List or disk fallback is sufficient for single‑service backends or small deployments.

The following cases should **not** be forced onto a lightweight queue:

• 支付状态变更  — 必须强一致性;
• 库存扣减  — 高并发且不可回滚;
• 跨服务事务  — 需要事务补偿;
• 严格顺序消费  — 多使用者组场景;
• 大吞吐量 + 消息回溯 + 死信治理链路 — Kafka / RabbitMQ / Pulsar 等成熟 MQ 更合适。
如果业务已经触及以上任意一点。请立刻评估换用专业 MQ，否则轻量队列只能解决“能看、能改、能重试”，而无法为业务提供可靠兜底。

我会怎么验收一条后台队列?

正常投递一条任务，确认使用者在日志中记录“处理成功”。

• 检查日志关键字如 “consume success” 或自定义审计标记。

sql SELECT * FROM xy_sys_queue_log WHERE topic='login' AND status='success' LIMIT 1;

Check Items Summary

Sorry this part got garbled due to length constraints – essential steps are:

1️⃣ 正常投递Push a message → verify consumer writes a success log. 2️⃣ 可重试错误Force consumer to return a retryable error → ensure retry increments but never exceeds max_retry. 3️⃣ 禁用 TopicSet status=0 → confirm both UI push API and consumer reject new messages. 4️⃣ 并发安全Increase workers → verify idempotent key prevents duplicate effects . 5️⃣ 权限回归Run migration script → check config table exists。menu entries have separate “view” & “edit” permissions,and corresponding API endpoints enforce RBAC.

This checklist is stored in repository’s /docs/queue‑acceptance.md file so that every PR can be automatically validated by CI.

---

The queue length can serve as an alarm entry point,but it must never be used as final acceptance verdict. The real questions are:

• 失败的任务去哪儿了？
• 谁有权修改配置？
• 重试是否会放大事故？
• 轻量队列到哪一步必须停下来换专业 MQ？ 把这些问题写进后台，比单纯展示一个数字更有价值。

---