mq-reliability
RabbitMQ / 消息队列可靠性契约:在写生产者或消费者前用五个入口问题定下可靠性级别、 幂等策略、重试与死信、顺序保障、积压预案,避免测试全绿但线上丢消息、重复执行、 积压失控的假绿陷阱。 在使用 RabbitMQ / Spring AMQP 写消息生产者或消费者、设计异步事件分发、 排查消息丢失 / 重复消费 / 积压 / 死信时使用。 触发信号:@RabbitListener、Rabbi
SKILL.mdskills/mq-reliability/SKILL.md
GitHubMQ 可靠性契约
模型对 RabbitMQ 基础配置(DLX / 重试 / durable)的判断已经够准(基线实测 3/3 全对),不必再写。 真正的缺口在测试全绿但线上出事的地方:DLQ 配了没人看、幂等不稳、积压无监控。 本技能只做三件事:把五个决策定下来、动手前读一遍、写完验证。
两条原则
- 五问先答,契约落盘。 第一次在项目里写消息代码时,把 D1–D5 的答案写进
.claude/rules/mq-reliability.md(提案-同意制,未经同意不写);之后每次动生产者/消费者前先读它。 读不到时按references/01-decisions.md的默认值写,并在回复里声明 「按 mq-reliability 默认,未读到项目契约」。 - 写完用假绿元判据自查。 测试环境不杀 broker、只投一次、消息量小——
把 broker 停掉 / 同条消息投两次 / 投 10 万条,你的代码会出什么问题?
想不出来就是还没想清楚,回
references/02-traps.md逐组过。
第一步:读项目
| 读什么 | 得到什么 |
|---|---|
pom.xml / build.gradle |
是否已有 spring-amqp / spring-rabbit 依赖 |
.claude/rules/mq-reliability.md |
项目已有的五问答案。读到才生效,读到就遵守 |
既有 @RabbitListener / RabbitTemplate |
既有惯例:ack 模式、幂等做法、拓扑风格 |
项目惯例与下表默认冲突时,惯例优先。
入口五问
写生产者或消费者前,五问都要有答案。漏一问就漏一个决策维度。
| # | 入口问题 | 决策什么 | 不答的后果 |
|---|---|---|---|
| D1 | 这条消息丢了会怎样? | 可靠性级别:confirm + 持久化 + ack 策略 | 静默丢消息 |
| D2 | 同一条消息处理两次会怎样? | 幂等策略:去重键 + 去重位置 | 重复扣款 / 重复通知 |
| D3 | 消费失败了消息去哪? | 重试次数 + DLX + DLQ 谁来看 | 毒消息死循环 / 死信黑洞 |
| D4 | 这些消息必须按顺序吗? | 单消费者 / 业务键分片 + SAC | 状态错乱 |
| D5 | 生产快过消费怎么办? | prefetch + 积压告警阈值 + 降级 | 积压无人知 |
展开见 references/01-decisions.md。
强约束
只收「写错后测试仍然绿」的。会红的(依赖缺失、API 签名错)不在表内。
| ✗ 禁止 | ✓ 推荐 | 假绿原因 |
|---|---|---|
| DLQ 配了没人看 | DLQ 挂消费者或告警,死信必须有人处理 | 测试不触发 DLQ 路径 |
| 累加型操作裸消费 | 按业务唯一键去重(DB 唯一键 / 状态机 / Redis setnx) | 重复投递累加翻倍 |
| 委托下游去重但没约定 | 自己去重,或与下游书面约定去重键与语义 | 下游没做 = 重复副作用 |
| 多步副作用 + AUTO ack 不想 crash | 多步副作用用手动 ack,或保证幂等后用 AUTO | JVM crash 后重投重复执行 |
| 不开 publisher confirm | 开 confirm + 处理 nack / return | 发送方不知道丢了 |
| 无队列深度监控 | 设积压告警阈值 | 测试消息量小测不出积压 |
| 不问 D4 就开多消费者 | 先答 D4;要顺序 → 单消费者或分片 + SAC | 多消费者打乱顺序 |
假绿陷阱详解见 references/02-traps.md。
与 java-contract 的边界
「重复到达」在 java-contract 管业务语义(返回上次结果、不重复执行),在本技能管传输语义 (MQ 可能投两次)。两层都要答,D2 的幂等策略涉及业务写操作时指向 java-contract 的「重复到达」条目。