@umacloud/knowledge 1.0.14 → 1.0.16

package/backend/01-standards/message-queue-patterns.md

@@ -1,379 +1,101 @@
 ---
 id: message-queue-patterns
-title: 消息队列模式完整指南
+title: 消息队列选型与消息模式规范（按场景选队列 + 用对消息模式，商业级必读）
 domain: backend
 category: 01-standards
-difficulty: intermediate
-tags: [backend, kafka, message, patterns, queue, rabbitmq, redis, streams]
-quality_score: 70
-last_updated: 2026-06-15
+difficulty: advanced
+tags: [message-queue, kafka, rabbitmq, redis-streams, broker-selection, pub-sub, work-queue, event-streaming, event-sourcing, cqrs, fanout, routing, partitioning, schema-evolution, 消息队列, 选型, 消息模式, 事件流, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
 ---
-# 消息队列模式完整指南
-
-## 概述
-
-消息队列是分布式系统的核心基础设施，实现服务解耦、异步处理、流量削峰和事件驱动架构。本指南覆盖 Kafka、RabbitMQ 和 Redis Streams 的选型、核心模式和最佳实践。
-
----
-
-## 方案选型对比
-
-| 特性 | Kafka | RabbitMQ | Redis Streams |
-|------|-------|----------|---------------|
-| 定位 | 分布式事件流平台 | 消息代理 | 轻量级消息流 |
-| 吞吐量 | 百万级/秒 | 万级/秒 | 十万级/秒 |
-| 消息持久化 | 磁盘，可配置保留期 | 内存+磁盘 | 内存+RDB/AOF |
-| 消费模型 | Consumer Group + Offset | Queue/Exchange 路由 | Consumer Group |
-| 消息顺序 | Partition 内有序 | Queue 内有序 | Stream 内有序 |
-| 延迟 | 毫秒级 | 微秒级 | 微秒级 |
-| 适用场景 | 事件溯源/日志/大数据 | 任务队列/RPC/路由 | 轻量事件/缓存层流 |
-
----
-
-## Kafka
-
-### 核心概念
-
-```
-Producer -> Topic (Partition 0, 1, 2...) -> Consumer Group
-                                             ├── Consumer A (Partition 0, 1)
-                                             └── Consumer B (Partition 2)
-```
-
-### 生产者
-
-```python
-from confluent_kafka import Producer
-
-producer = Producer({
-    "bootstrap.servers": "kafka:9092",
-    "acks": "all",                    # 等待所有副本确认
-    "retries": 3,
-    "enable.idempotence": True,       # 幂等生产者
-    "max.in.flight.requests.per.connection": 5,
-})
-
-def send_event(topic: str, key: str, value: dict):
-    import json
-    producer.produce(
-        topic=topic,
-        key=key.encode("utf-8"),
-        value=json.dumps(value).encode("utf-8"),
-        callback=delivery_report,
-    )
-    producer.flush()
-
-def delivery_report(err, msg):
-    if err:
-        logger.error(f"Message delivery failed: {err}")
-    else:
-        logger.info(f"Message delivered to {msg.topic()} [{msg.partition()}]")
-```
-
-### 消费者
-
-```python
-from confluent_kafka import Consumer, KafkaError
-
-consumer = Consumer({
-    "bootstrap.servers": "kafka:9092",
-    "group.id": "order-service",
-    "auto.offset.reset": "earliest",
-    "enable.auto.commit": False,     # 手动提交 offset
-    "max.poll.interval.ms": 300000,
-})
-
-consumer.subscribe(["order-events"])
-
-try:
-    while True:
-        msg = consumer.poll(timeout=1.0)
-        if msg is None:
-            continue
-        if msg.error():
-            if msg.error().code() == KafkaError._PARTITION_EOF:
-                continue
-            raise KafkaException(msg.error())
-
-        try:
-            event = json.loads(msg.value().decode("utf-8"))
-            process_order_event(event)
-            consumer.commit(msg)     # 处理成功后手动提交
-        except ProcessingError as e:
-            logger.error(f"Failed to process: {e}")
-            send_to_dlq(msg)         # 发送到死信队列
-            consumer.commit(msg)
-finally:
-    consumer.close()
-```
-
-### Kafka 最佳实践
-
-- **分区数**: 通常等于消费者数量的倍数
-- **Key 设计**: 使用业务 ID 保证同一实体的消息有序
-- **保留策略**: 根据业务需求设置（7 天/30 天/永久）
-- **压缩**: 使用 lz4 或 snappy 减少网络和存储开销
-
----
-
-## RabbitMQ
-
-### Exchange 类型
-
-```
-Direct:   routing_key 精确匹配
-Fanout:   广播到所有绑定队列
-Topic:    routing_key 模式匹配 (*.error, order.#)
-Headers:  基于 header 属性匹配
-```
-
-### 生产者
-
-```python
-import pika
-import json
-
-connection = pika.BlockingConnection(pika.ConnectionParameters(
-    host="rabbitmq",
-    credentials=pika.PlainCredentials("guest", "guest"),
-    heartbeat=600,
-))
-channel = connection.channel()
-
-# 声明持久化队列和交换机
-channel.exchange_declare(exchange="orders", exchange_type="topic", durable=True)
-channel.queue_declare(queue="order-processing", durable=True)
-channel.queue_bind(queue="order-processing", exchange="orders", routing_key="order.created")
-
-def publish_order_event(order_id: str, event_type: str, data: dict):
-    channel.basic_publish(
-        exchange="orders",
-        routing_key=f"order.{event_type}",
-        body=json.dumps({"order_id": order_id, **data}),
-        properties=pika.BasicProperties(
-            delivery_mode=2,        # 持久化消息
-            content_type="application/json",
-            message_id=str(uuid.uuid4()),
-            timestamp=int(time.time()),
-        ),
-    )
-```
-
-### 消费者
-
-```python
-def callback(ch, method, properties, body):
-    try:
-        event = json.loads(body)
-        process_order(event)
-        ch.basic_ack(delivery_tag=method.delivery_tag)
-    except Exception as e:
-        logger.error(f"Processing failed: {e}")
-        # 拒绝并重新入队（或发送到 DLQ）
-        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
-
-channel.basic_qos(prefetch_count=10)  # 流控
-channel.basic_consume(queue="order-processing", on_message_callback=callback)
-channel.start_consuming()
-```
-
-### 死信队列 (DLQ)
-
-```python
-# 声明 DLQ
-channel.queue_declare(queue="order-processing-dlq", durable=True)
-
-# 主队列绑定 DLQ
-channel.queue_declare(
-    queue="order-processing",
-    durable=True,
-    arguments={
-        "x-dead-letter-exchange": "",
-        "x-dead-letter-routing-key": "order-processing-dlq",
-        "x-message-ttl": 86400000,     # 消息 TTL: 24h
-        "x-max-length": 100000,        # 队列最大长度
-    },
-)
-```
-
----
-
-## Redis Streams
-
-### 基本操作
-
-```python
-import redis
-
-r = redis.Redis(host="localhost", port=6379, decode_responses=True)
-
-# 生产者：添加消息到 Stream
-message_id = r.xadd("order-events", {
-    "order_id": "ORD-001",
-    "event": "created",
-    "amount": "99.99",
-    "timestamp": str(int(time.time())),
-})
-
-# 创建消费者组
-r.xgroup_create("order-events", "order-service", id="0", mkstream=True)
-
-# 消费者：读取消息
-while True:
-    messages = r.xreadgroup(
-        groupname="order-service",
-        consumername="worker-1",
-        streams={"order-events": ">"},
-        count=10,
-        block=5000,
-    )
-
-    for stream, entries in messages:
-        for msg_id, fields in entries:
-            try:
-                process_event(fields)
-                r.xack("order-events", "order-service", msg_id)
-            except Exception as e:
-                logger.error(f"Failed: {e}")
-                # 消息留在 PEL 中，稍后重试
-
-# 处理 pending 消息（故障恢复）
-pending = r.xpending_range("order-events", "order-service", "-", "+", count=100)
-for entry in pending:
-    if entry["time_since_delivered"] > 300000:  # 超过 5 分钟未确认
-        messages = r.xclaim(
-            "order-events", "order-service", "worker-1",
-            min_idle_time=300000,
-            message_ids=[entry["message_id"]],
-        )
-        for msg_id, fields in messages:
-            reprocess_event(fields)
-            r.xack("order-events", "order-service", msg_id)
-```
-
----
-
-## 事件驱动架构模式
-
-### 事件溯源 (Event Sourcing)
-
-```python
-# 事件存储
-class EventStore:
-    def __init__(self, producer: KafkaProducer):
-        self.producer = producer
-
-    def append(self, aggregate_id: str, event: DomainEvent):
-        self.producer.send(
-            topic=f"events-{event.aggregate_type}",
-            key=aggregate_id,
-            value={
-                "event_id": str(uuid.uuid4()),
-                "aggregate_id": aggregate_id,
-                "event_type": event.__class__.__name__,
-                "data": event.to_dict(),
-                "version": event.version,
-                "timestamp": datetime.utcnow().isoformat(),
-            },
-        )
-
-# 事件重放
-class OrderAggregate:
-    def __init__(self):
-        self.status = None
-        self.items = []
-        self.total = 0
-
-    def apply(self, event: DomainEvent):
-        if isinstance(event, OrderCreated):
-            self.status = "created"
-            self.items = event.items
-        elif isinstance(event, OrderPaid):
-            self.status = "paid"
-            self.total = event.amount
-```
-
-### 幂等消费者
-
-```python
-class IdempotentConsumer:
-    def __init__(self, redis_client: redis.Redis):
-        self.redis = redis_client
-        self.ttl = 86400 * 7  # 7 天去重窗口
-
-    def process(self, message_id: str, handler: Callable):
-        key = f"processed:{message_id}"
-        if self.redis.exists(key):
-            logger.info(f"Duplicate message {message_id}, skipping")
-            return
-
-        handler()
-
-        self.redis.set(key, "1", ex=self.ttl)
-```
-
-### 重试策略
-
-```python
-import time
-from functools import wraps
-
-def retry_with_backoff(max_retries=3, base_delay=1.0, max_delay=60.0):
-    def decorator(func):
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            for attempt in range(max_retries + 1):
-                try:
-                    return func(*args, **kwargs)
-                except RetryableError as e:
-                    if attempt == max_retries:
-                        raise
-                    delay = min(base_delay * (2 ** attempt), max_delay)
-                    jitter = delay * 0.1 * random.random()
-                    time.sleep(delay + jitter)
-                    logger.warning(f"Retry {attempt + 1}/{max_retries}: {e}")
-        return wrapper
-    return decorator
-```
-
----
-
-## 监控指标
-
-| 指标 | 说明 | 告警阈值 |
-|------|------|----------|
-| Consumer Lag | 消费者落后的消息数 | > 10000 |
-| Message Rate | 每秒消息产生/消费量 | 异常波动 |
-| Error Rate | 处理失败率 | > 1% |
-| DLQ Size | 死信队列堆积数 | > 100 |
-| Processing Latency | 消息处理延迟 P99 | > 5s |
-
----
-
-## 常见反模式
-
-| 反模式 | 问题 | 正确做法 |
-|--------|------|----------|
-| 消息体过大 | 网络/存储开销 | 消息只传 ID + 元数据，数据走存储 |
-| 不做幂等 | 重复处理 | 消息 ID 去重 + 幂等写入 |
-| 自动提交 offset | 消息丢失 | 处理成功后手动提交 |
-| 忽略 DLQ | 失败消息丢失 | 配置死信队列并监控 |
-| 无重试策略 | 临时故障导致消息丢失 | 指数退避重试 |
-| 强依赖消息顺序 | 扩展困难 | 仅在必要时保证分区内有序 |
-
----
-
-## Agent Checklist
-
-- [ ] 根据吞吐量和延迟需求选择合适的消息队列
-- [ ] 生产者启用幂等写入和重试
-- [ ] 消费者手动提交 offset/ack
-- [ ] 实现幂等消费者（消息 ID 去重）
-- [ ] 配置死信队列 (DLQ) 并监控大小
-- [ ] 实现指数退避重试策略
-- [ ] 消息体控制在 1MB 以内
-- [ ] Kafka 分区 Key 设计保证业务有序性
-- [ ] 消费者 Group 内消费者数 <= 分区数
-- [ ] 监控 Consumer Lag / Error Rate / DLQ Size
-- [ ] 消息 Schema 有版本管理（Avro/Protobuf + Schema Registry）
-- [ ] 生产环境 Kafka 至少 3 副本，acks=all
+# 消息队列选型与消息模式规范（商业级必读）
+
+> 引入消息队列前先答两个问题：**选哪种队列**、**用哪种消息模式**。选错队列，要么吞吐扛不住、要么为简单任务上了重平台；用错模式，要么把事件流当任务队列、要么把广播写成点对点，越用越拧巴。
+> 本规范只解决"选型 + 模式"：按场景把队列类型选对、把生产/消费模式用对。**消费侧怎么写才可靠**（投递语义、幂等有效一次、可见性超时、顺序、毒消息与死信、背压）是另一件事，见 `backend/01-standards/queue-and-consumer-reliability`，本文不重复；**任务该不该异步、怎么编排**见 `backend/01-standards/background-jobs-and-async`。
+
+## 1. 三类队列定位（先分清你要什么）
+
+| 维度 | 事件流平台（如 Kafka 类） | 消息代理（如 RabbitMQ 类） | 轻量流（如 Redis Streams 类） |
+|---|---|---|---|
+| 定位 | 持久化、可重放的事件日志 | 灵活路由的任务/消息分发 | 进程内/小规模轻量事件流 |
+| 量级 | 极高吞吐、海量留存 | 中等吞吐、复杂路由 | 中等吞吐、低运维成本 |
+| 消费模型 | 消费组 + 位点（offset），可回放 | 队列/交换机路由，消费即出队 | 消费组 + PEL（待确认列表） |
+| 留存与重放 | 按保留期留存，可重放历史 | 通常消费即删除，不便重放 | 可留存一段，能重放近期 |
+| 有序粒度 | 分区内有序 | 队列内有序 | 流内有序 |
+| 典型场景 | 事件溯源、日志聚合、数据管道、多消费方 | 任务队列、RPC、按规则路由分发 | 轻量异步、已有该存储栈、低门槛 |
+
+**选型判据**：需要**重放历史 / 多个独立消费方 / 超高吞吐** → 事件流平台；需要**复杂路由 / 每条消息一次性派给一个工作者** → 消息代理；**规模不大、已有该内存存储、想省一套中间件** → 轻量流。别为一个定时任务上重型事件平台，也别用轻量流硬扛海量留存与回放。
+
+## 2. 选型决策清单（按需求倒推）
+
+| 需求信号 | 倾向选择 |
+|---|---|
+| 同一份事件要被多个团队/服务各自独立消费 | 事件流平台（消费组互不影响 + 可回放） |
+| 要按 routing key / header 把消息精确分发到不同队列 | 消息代理（交换机路由能力强） |
+| 吞吐在十万～百万级、需长期留存与重算 | 事件流平台 |
+| 经典工作队列：N 个 worker 抢任务，处理完即删 | 消息代理 |
+| 团队已重度使用某内存存储、不想新增运维面 | 轻量流（够用即可） |
+| 强延迟敏感 + 简单点对点 | 消息代理 / 轻量流 |
+
+选型还要算**运维成本**：事件流平台能力最强但运维最重（分区、副本、保留、再平衡都要管）；轻量流最省心但能力边界明显。能力够用的前提下，**选运维最轻的那个**。
+
+## 3. 核心生产/消费模式
+
+| 模式 | 用途 | 关键点 |
+|---|---|---|
+| 工作队列 work queue | N 个消费者瓜分任务 | 每条消息只被一个消费者成功处理；按预取控制并发 |
+| 发布订阅 pub/sub（fanout） | 一条消息广播给所有订阅方 | 每个订阅方一份；新增订阅方不影响既有 |
+| 路由/主题 routing/topic | 按 key/pattern 精确或模式投递 | 路由键设计决定可扩展性，别用一个万能队列 |
+| 分区有序 partitioned | 同实体有序、跨实体并行 | 用实体键路由到同一分区，仅保证分区内有序（顺序细节见 reliability 文档） |
+| 请求/响应 over MQ | 异步 RPC | 用 correlation-id + 回复队列；超时要兜底，别永久等 |
+
+## 4. 关键设计点（选型之后立刻要定）
+
+- **分区/路由键设计**：键决定**并行度与有序性**。用业务实体 ID 作分区键，让同一实体落同一分区（有序）、不同实体散开（并行）。键选错会造成热分区或丧失可扩展性。
+- **消费者数 ≤ 分区数**：事件流平台里，消费组内并行度受分区数上限制约；分区数要按目标吞吐与未来扩容预留。
+- **消息载荷小而稳**：消息传 **ID/引用 + 必要元数据**，大对象走对象存储，别把大 blob 塞进消息体撑爆网络与留存。
+- **Schema 演进有契约**：消息体用带版本的结构化 Schema（如 Avro/Protobuf/JSON + 版本字段 + Schema Registry 思路），**只做向后兼容的演进**（加可选字段，不改语义、不删必填），消费者要容忍未知新增字段。
+- **保留与回放策略**：事件流平台明确保留期（按业务与重算需求）；用到回放时，消费者必须**幂等**才能安全重放（见 reliability 文档）。
+- **多消费方解耦**：同一事件被多方消费时，用独立消费组/订阅，彼此进度互不影响，杜绝"一个慢消费方拖垮其他人"。
+
+## 5. 事件驱动架构模式（选型支撑的上层玩法）
+
+- **事件溯源 Event Sourcing**：以**事件序列**为真相源，状态由事件重放得出。要求底座支持持久化与有序回放（事件流平台是天然载体）；聚合重建依赖事件幂等可重放。
+- **CQRS**：写侧产生事件，读侧消费事件构建查询视图，读写分离各自扩展。注意读模型是**最终一致**的，UI/契约要承认这点。
+- **Saga / 事件编排**：跨服务长流程用事件串联，每步有补偿动作，避免分布式强事务（分布式事务取舍见 `architecture/distributed-transactions`）。
+- **Outbox 投递**：业务写库与"待发事件"同事务落库，再由投递器异步发出，杜绝"库改了消息没发/消息发了库回滚"（端到端可靠属 reliability 文档范畴）。
+
+## 6. 监控与容量（选型落地的运维基线）
+
+| 指标 | 看什么 | 含义 |
+|---|---|---|
+| 消费滞后 lag | 消费组落后生产的量 | 持续增长 = 消费跟不上，要扩容/优化/限流 |
+| 生产/消费速率 | 每秒入队/出队 | 异常骤变是上游异常或消费停摆的早信号 |
+| 死信堆积 | DLQ 大小 | 堆积说明有系统性失败（处置见 reliability 文档） |
+| 处理延迟 | 入队到处理完的 P99 | 端到端时延，影响业务体验 |
+| 分区均衡 | 各分区流量/lag 分布 | 不均 = 路由键设计问题（热分区） |
+
+容量上：分区数、消费者并发、留存大小要**按目标峰值预留余量**，别按当前流量卡满；扩容路径（加分区/加消费者）要提前想清楚，事件流平台的分区数通常**只能增不能减**。
+
+## 7. 反模式（出现即不合格）
+
+1. **场景与队列错配**：为简单定时任务上重型事件平台，或用轻量流硬扛海量留存与回放。
+2. **一个万能队列**：所有消息塞进一个队列/主题，不做路由与隔离，无法独立扩展与监控。
+3. **路由键/分区键拍脑袋**：键设计不当导致热分区、丧失有序性或无法并行。
+4. **大对象进消息体**：把大 blob 塞进消息，撑爆网络、留存与重放成本。
+5. **Schema 无版本、破坏性演进**：改语义/删必填字段，消费者直接崩。
+6. **多消费方共用一个消费组**：本该独立消费的多方互相抢消息、互相拖累。
+7. **消费者数 > 分区数还指望线性扩展**：多出来的消费者空转，吞吐上不去。
+8. **不监控 lag 与分区均衡**：消费早跟不上或热分区，积压到爆才发现。
+9. **把可靠性细节当选型问题糊弄**：投递语义/幂等/死信不按 reliability 规范做（见交叉引用）。
+
+## 8. 最低交付 checklist
+
+- [ ] 按"重放/多消费方/超高吞吐 vs 复杂路由 vs 轻量省心"把队列类型选对，并算了运维成本。
+- [ ] 分区/路由键用业务实体 ID 设计，同实体有序、跨实体并行；消费者数 ≤ 分区数。
+- [ ] 消息载荷小（传 ID/引用），大对象走对象存储。
+- [ ] 消息 Schema 带版本、只做向后兼容演进，消费者容忍未知新增字段。
+- [ ] 事件流平台明确保留期与回放策略；多消费方用独立消费组解耦。
+- [ ] 监控 lag / 速率 / DLQ / 处理延迟 / 分区均衡，容量按峰值预留并想清扩容路径。
+- [ ] 事件溯源/CQRS/Saga/Outbox 等上层模式按需选用，承认读模型最终一致。
+- [ ] 消费侧可靠性（投递语义/幂等有效一次/可见性超时/顺序/毒消息/背压）按 `backend/01-standards/queue-and-consumer-reliability` 落地，本文不重复。

package/backend/01-standards/queue-and-consumer-reliability.md

@@ -0,0 +1,98 @@
+---
+id: queue-and-consumer-reliability
+title: 队列与消费者可靠性规范（投递语义/幂等有效一次/顺序/可见性超时/毒消息，商业级必读）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [queue, consumer, reliability, idempotent-consumer, effectively-once, at-least-once, dead-letter-queue, poison-message, visibility-timeout, redelivery, ordering, backpressure, consumer-lag, outbox, inbox, 队列, 消费者, 幂等, 有效一次, 死信, 毒消息, 可见性超时, 顺序, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 队列与消费者可靠性规范（商业级必读）
+
+> 异步队列把"耗时/可削峰"的工作从请求路径里挪走，但也引入一组分布式难题：消息会**重复投递**、会**乱序**、会**卡住**、会**毒死消费者**。把这些当"偶发"忽略，结果就是重复扣款、订单错乱、队列雪崩、一条坏消息阻塞整条队列。
+> 这份规范讲的不是选哪个队列产品（选型与各产品用法见 `backend/01-standards/message-queue-patterns`），也不只是"任务该不该异步"（任务编排见 `backend/01-standards/background-jobs-and-async`），而是**消费侧怎么写才可靠**：投递语义、幂等与有效一次、顺序、可见性超时与重投、毒消息与死信、背压与堆积。
+
+## 1. 先认清投递语义（一切的前提）
+
+| 语义 | 含义 | 现实可得性 |
+|---|---|---|
+| 至多一次 at-most-once | 不重复，但可能丢 | 简单，但丢消息通常不可接受 |
+| 至少一次 at-least-once | 不丢，但可能重复 | **主流默认**——必须假设会重复 |
+| 恰好一次 exactly-once | 不丢不重 | 端到端几乎不存在；分布式下是营销词 |
+
+**结论：按"至少一次 + 可能乱序 + 可能重投"来设计。** 真正能做到的不是传输层的"恰好一次",而是**业务上的"有效一次"（effectively-once）**——传输可以重复投递,但靠**消费幂等**保证副作用只发生一次。任何依赖"队列保证不重复"的设计都是错的。
+
+## 2. 幂等消费与有效一次（核心中的核心）
+
+同一条消息可能被投递 2 次、5 次（重投、重平衡、消费者崩溃后重启都会导致）。涉钱/发货/发邮件/外部副作用的消费**必须幂等**：
+
+- **去重键**：用稳定的业务键或消息 ID 作为去重依据（生产者要保证同一逻辑事件用同一 ID）。
+- **去重落地**：处理前检查"这个 ID 处理过吗"，处理后记录；去重表/标记要和业务副作用在**同一事务**里提交，否则"业务做了但没记上去重"仍会重复。
+- **首选天然幂等写**：`UPSERT`、`SET 状态=已支付`、条件更新（`WHERE 状态=待支付`）这类操作天然幂等，优于"先查再插"的竞态写法。
+- **去重窗口**：去重记录保留足够覆盖最大可能重投间隔（含 DLQ 重放),并有清理策略防无限增长。
+- **副作用收口**：把外部副作用（扣款/发消息）做成可幂等或带幂等键调用（见 `backend/01-standards/idempotency-and-safe-retries`）。
+
+## 3. 可见性超时与重投机制
+
+至少一次队列普遍用"取出即隐藏一段时间（可见性超时 / ack 截止），处理完确认（ack），否则到期重新可见被别人取"的机制。用错会**自伤**：
+
+- **处理完才确认**：先处理成功、再 ack/提交位点；**绝不**取出就自动确认（自动提交 = 崩溃即丢消息）。
+- **可见性超时 > 处理耗时**：超时必须覆盖正常处理时间 + 余量。设太短 → 还没处理完消息就被重新投递给另一个消费者，造成**并发重复处理**；设太长 → 真崩溃了消息长时间不重投，延迟恢复。
+- **长任务续租**：处理时间不确定的任务要在处理中**续租/心跳延长**可见性，而不是一开始设一个超大超时。
+- **确认要可靠**：ack/提交本身失败要能感知；位点提交粒度与"处理成功"对齐,避免提交了未处理或处理了未提交。
+
+## 4. 顺序：只在必要处保证，别全局强序
+
+全局严格有序和高吞吐/可扩展天然冲突。
+
+- **按需分区有序**：只对**同一实体**（同一订单/同一账户）要求有序——用实体键路由到同一分区/队列，保证**分区内**有序即可，不同实体并行处理。
+- **别假设跨分区有序**：多分区/多消费者天然乱序;业务逻辑不能依赖"先发的先到"。
+- **乱序容忍设计**：用版本号/时间戳/状态机让消费对乱序与重复**收敛到正确终态**（如旧版本更新被丢弃、状态只能单向前进），比强行保序更健壮。
+- **有序与重试的张力**：严格有序队列里,一条卡住的消息会阻塞其后全部——更需要快速隔离毒消息（见 §5）。
+
+## 5. 毒消息与死信队列（DLQ）
+
+"毒消息"（poison message）= 无论重试多少次都必然失败的消息（数据损坏、不可解析、触发确定性 bug）。不隔离它,它会反复重试**阻塞队列、刷爆日志、耗尽资源**。
+
+- **限次重试 + 退避抖动**：瞬时失败重试有限次,指数退避 + 抖动(避免重试风暴);区分**可重试**(网络/限流/5xx)与**不可重试**(解析失败/校验不过/业务拒绝)——不可重试的别浪费重试,直接进 DLQ。
+- **超限进 DLQ**：超过重试上限的消息移入死信队列,**带上下文**(原消息 + 失败原因 + 重试次数 + 时间),不静默丢弃。
+- **DLQ 必须被监控与处置**：DLQ 不是垃圾桶——堆积要告警,要有人看、能诊断、能修复后**重放**。DLQ 无人管 = 消息悄悄全丢。
+- **隔离优先于阻塞**：宁可让一条坏消息进 DLQ,也不要让它卡住整条队列拖垮正常消息。
+
+## 6. 背压、堆积与消费者健康
+
+- **监控消费滞后(lag)**：盯消费者落后量(待处理积压)。lag 持续增长 = 消费跟不上生产,要么扩消费者、要么限生产、要么优化处理。
+- **有界并发与预取**：消费者设合理预取/并发上限,别一次抓太多撑爆内存或长时间占住不 ack。
+- **背压而非无限缓冲**:下游处理不过来时传递背压(放慢拉取/拒绝),不要把消息全拉进内存无界堆积到 OOM。
+- **慢消费者隔离**:不同类型任务用不同队列/消费者池,一类慢任务别拖垮另一类(呼应 `backend/01-standards/resilience-and-fault-tolerance` 的舱壁)。
+- **优雅停机**:消费者收到停止信号要处理完在途消息(或安全释放回队列)再退出,不硬切。
+
+## 7. 生产侧可靠性：别在源头就丢/错
+
+- **入队与事务一致(outbox)**:"写库 + 发消息"要么都成要么都不成。用 **outbox 模式**——业务与"待发消息"同事务写库,再由投递器异步发出——避免"事务回滚了消息却发了"或"事务提交了消息没发"。
+- **消费幂等也要 inbox 思路**:接收侧记录已处理消息 ID(inbox),配合 outbox 构成端到端有效一次。
+- **载荷小而稳**:消息传 ID/引用而非大对象;Schema 带版本,演进保持兼容,消费者能容忍新增字段。
+
+## 8. 反模式（出现即不合格）
+
+1. **假设恰好一次**:依赖队列"不会重复",消费不幂等 → 重复扣款/重复发货。
+2. **取出即自动确认**:auto-ack/自动提交位点,消费者一崩消息就丢。
+3. **可见性超时短于处理**:消息处理中就被重投,并发重复处理。
+4. **毒消息无限重试**:一条坏消息反复失败阻塞队列、刷爆日志、烧资源。
+5. **有 DLQ 没人看**:死信堆积无告警无重放,消息悄悄全丢。
+6. **全局强序**:为顺序牺牲扩展性,一条卡住阻塞全部。
+7. **无界拉取/缓冲**:消费者一次抓太多或无限缓冲,OOM。
+8. **不监控 lag**:消费早已跟不上,积压到爆才发现。
+9. **入队与事务不一致**:无 outbox,消息与数据状态错位。
+
+## 9. 最低交付 checklist
+
+- [ ] 按"至少一次 + 可能乱序"设计;靠消费幂等实现业务"有效一次"。
+- [ ] 用稳定去重键,去重记录与业务副作用同事务提交;优先天然幂等写。
+- [ ] 处理成功后才 ack/提交位点;可见性超时 > 处理耗时,长任务续租。
+- [ ] 仅对同一实体按分区保证有序,业务对乱序/重复能收敛到正确终态。
+- [ ] 限次重试 + 退避抖动,区分可重试/不可重试;超限进带上下文的 DLQ。
+- [ ] DLQ 有监控告警、可诊断、可重放;坏消息隔离而非阻塞整队。
+- [ ] 监控消费 lag;有界并发/预取 + 背压;慢消费者隔离;消费者优雅停机。
+- [ ] 生产侧用 outbox 保证入队与事务一致;载荷小、Schema 带版本兼容演进。