Mq Design

---
name: mq-design
description: 为 Go 后端设计异步消息：选择 Kafka 或 RabbitMQ，设计 topic / 交换机与队列、消息格式、确认与重试、幂等消费，产出设计文档与运维创建清单。用户说「加消息队列」「异步处理」「设计 topic」「设计队列」「消息重复消费」「消息丢失」时使用。只修改已有消费者的业务逻辑时不使用。
---

# 消息队列设计

逐条规则在 `.claude/rules/mq/kafka.md` 与 `.claude/rules/mq/rabbitmq.md`，编辑消息相关代码时自动加载；客户端参数见 `references/client-config.md`。

## 1. 选型

| 需求 | 选择 |
|---|---|
| 高吞吐、事件流、日志采集、多个消费方独立回放 | Kafka |
| 可靠投递、复杂路由、按消息确认、延迟或优先级队列 | RabbitMQ |
| 只是缓存数据或计数 | 不用消息队列，用 Redis |

Redis 不作为消息队列。项目已经使用其中一种时，除非有明确理由，沿用现有的。

## 2. 设计消息

- 消息体用 JSON 或 Protobuf，带 `event_id`（全局唯一，用于去重）、`event_type`、`occurred_at` 和版本号。
- 只放消费方需要的数据；大对象存到对象存储后传引用。Kafka 单条不超过 1MB，RabbitMQ 不超过 500KB。
- 需要顺序时说明顺序的范围（同一订单、同一用户），Kafka 用该业务键作为消息 key。

## 3. 可靠性

逐项写明：

| 环节 | 要回答的问题 |
|---|---|
| 生产 | 数据库写入和发送消息如何保持一致？（本地消息表 / outbox，或事务消息）确认级别是什么？ |
| 消费 | 何时确认 / 提交 offset？失败如何重试，重试几次，最终进入哪里（死信队列 / 重试 topic）？ |
| 幂等 | 用什么去重：`event_id` 去重表、业务唯一键，还是状态机条件更新？ |
| 积压 | 积压时如何扩容消费者？Kafka 的消费者数量受分区数限制 |

## 4. 资源创建清单

topic、交换机、队列由运维或 IaC 创建，代码不自动创建。在设计文档中提供清单：

- Kafka：topic 名、分区数、副本数、保留时间、预估消息大小与每秒条数、生产方与消费方服务、consumer group 名
- RabbitMQ：vhost、交换机名与类型、队列名、绑定键、是否持久化、死信配置、预估消息大小与速率、生产方与消费方服务

## 5. 产出

设计文档 `docs/design/<模块>-mq.md`：消息流图（Mermaid）、消息格式、可靠性方案、资源清单。实现后自查对应的 rules。