004|RabbitMQ 快速上手:核心概念与第一条消息
用 Python 和 Pika 跑通 RabbitMQ 的生产、路由与手动确认,分清 Exchange、Queue、发布确认和消费 ACK,并通过无路由、坏消息和依赖故障观察边界。
先给结论:RabbitMQ 最容易上手的方式,是先看清“消息路由到哪里”和“谁在何时确认”这两条线,再写生产者、消费者。本文用 Python 发送一条 JSON 消息,确认它进入指定队列,并在处理完成后手动确认;同时演示无路由、坏消息和临时故障。
适用场景:第一次接触 RabbitMQ,或者过去能跑通示例,但说不清 Exchange、Queue、ACK 分工的开发者。本文是本地学习环境,不是生产部署方案。
一、先统一环境和示例边界
本文采用 RabbitMQ 4.4.0、AMQP 0-9-1 协议、Python 3.12,以及 Pika 1.4.4。RabbitMQ 官方发布信息确认 4.4.0 于 2026 年 10 月发布;Pika 1.4.4 是正式发行版,这里不使用当时的 1.5 预发布版本。RabbitMQ 发布信息、Pika 1.4.4
示例显式声明单节点 classic queue,目的是用较少的组件看清路由和确认。它没有多副本高可用能力;后续讨论 quorum queues、streams 时会另行说明,不能把本例的存储与故障结论套到所有 RabbitMQ 队列。
以下代码和命令已完成文档、接口和语法核对,尚未在真实 Broker 上执行。文中的运行现象是待复现的预期,不是实测结果。
二、先认识消息经过的六个对象
可以把本次消息路径画成这样:
生产者
-> Exchange: mq.demo
-> Binding: routing_key = work
-> Queue: mq.demo.work
-> 消费者
-> 手动 ACK
Connection 是客户端到 Broker 的连接;Channel 是连接中的逻辑通道,本例在一个连接内建立一个 Channel。
Exchange 根据规则路由消息;Queue 承载等待消费或确认的消息;Binding 把队列与交换机连接起来;Routing Key 是发布时提供的路由信息。消费者订阅的是队列,生产者发布到的是交换机。Exchange 官方说明
本例选 direct exchange,绑定键是 work,发布时也使用 work,两者匹配后消息才能进入工作队列。Exchange 类型决定“往哪些队列分发”,并不决定消费者如何完成业务。
另有一个 mq.demo.failed 队列,用来隔离格式错误的样本。它通过内置默认交换机接收死信,不是第二个正常消费分组。
消息正文在协议里是字节数据,JSON 是本文为了便于观察而选择的业务格式。content_type="application/json" 是消息属性,不会让 Broker 自动替应用校验字段;所以消费者仍然检查对象类型、事件 ID 和正文结构。
本例把同一个事件 ID 同时放进消息属性与 JSON 正文,是为了让生产日志、Broker 观察和业务日志更容易对齐。它不应该在每次网络重试时随意变化;但不同业务事件也不能为了“去重”而共用一个固定 ID。
三、启动本地服务,安装 Python SDK
先准备已安装并运行的 Docker,再执行下面的命令。端口只绑定回环地址,示例账号密码只用于本机教学。
docker volume create mq-rabbitmq-demo-data
docker run -d \
--name mq-rabbitmq-demo \
--hostname mq-rabbitmq-demo \
-p 127.0.0.1:5672:5672 \
-p 127.0.0.1:15672:15672 \
-e RABBITMQ_DEFAULT_USER=mq_demo \
-e RABBITMQ_DEFAULT_PASS=mq_demo_only_2026 \
-v mq-rabbitmq-demo-data:/var/lib/rabbitmq \
rabbitmq:4.4.0-management
docker exec mq-rabbitmq-demo rabbitmq-diagnostics -q ping
5672 是本例 AMQP 客户端连接端口,15672 是管理界面端口。服务刚启动时检查可能还没通过,查看容器日志,待启动完成后再重试。浏览器访问 http://127.0.0.1:15672,使用上面的教学账号登录。
mkdir rabbitmq-demo
cd rabbitmq-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'pika==1.4.4'
Python 客户端使用 / 这个虚拟主机,连接 URL 末尾的 %2F 就是它的编码。虚拟主机隔离拓扑和权限;如果换了地址、用户或 vhost,需要一并核对授权,不能只看 TCP 端口能否连通。
下面两个文件都保存在这个目录。相同名称的交换机和队列可以重复声明,但声明属性必须一致;如果已存在同名实验队列且类型、持久性或参数不同,会收到 PRECONDITION_FAILED,应使用新的实验名称或检查旧队列,不能直接删除有真实数据的队列。
四、生产者:持久消息、发布确认和路由检查
文件:producer.py。
import argparse
import json
import os
import sys
import uuid
import pika
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--count", type=int, default=1)
parser.add_argument("--message-id")
parser.add_argument("--routing-key", default="work")
parser.add_argument("--bad-json", action="store_true")
args = parser.parse_args()
if not 1 <= args.count <= 10000:
parser.error("count 必须在 1 到 10000 之间")
if args.message_id and args.count != 1:
parser.error("固定 message-id 时 count 必须为 1")
params = pika.URLParameters(os.environ.get(
"AMQP_URL",
"amqp://mq_demo:mq_demo_only_2026@127.0.0.1:5672/%2F",
))
params.heartbeat = 60
params.blocked_connection_timeout = 30
params.socket_timeout = 10
params.stack_timeout = 15
connection = None
event_id = None
try:
connection = pika.BlockingConnection(params)
channel = connection.channel()
channel.exchange_declare("mq.demo", exchange_type="direct", durable=True)
channel.queue_declare("mq.demo.failed", durable=True,
arguments={"x-queue-type": "classic"})
channel.queue_declare("mq.demo.work", durable=True, arguments={
"x-queue-type": "classic",
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "mq.demo.failed",
})
channel.queue_bind("mq.demo.work", "mq.demo", routing_key="work")
# 确认解决 Broker 接收责任,mandatory 另行检查无路由返回。
channel.confirm_delivery()
for index in range(args.count):
event_id = args.message_id or uuid.uuid4().hex
event = {"event_id": event_id, "text": f"开发笔记 {index + 1}"}
body = b"{" if args.bad_json else json.dumps(
event, ensure_ascii=False,
).encode("utf-8")
channel.basic_publish(
exchange="mq.demo", routing_key=args.routing_key, body=body,
properties=pika.BasicProperties(
content_type="application/json", content_encoding="utf-8",
delivery_mode=2, message_id=event_id,
), mandatory=True,
)
print(f"Broker 已确认 event_id={event_id}", flush=True)
return 0
except pika.exceptions.UnroutableError:
print(f"没有可路由的目标队列 event_id={event_id}", file=sys.stderr)
return 2
except pika.exceptions.NackError:
print(f"Broker 拒绝本次发布 event_id={event_id}", file=sys.stderr)
return 3
except (pika.exceptions.AMQPError, OSError) as exc:
# 断线不等于未写入;保留业务 ID,交给上层判断和重试。
print(f"连接或协议失败,发布结果需核对 event_id={event_id}: {exc}",
file=sys.stderr)
return 1
finally:
if connection is not None and connection.is_open:
try:
connection.close()
except pika.exceptions.AMQPError:
pass
if __name__ == "__main__":
sys.exit(main())
这里有三个不同的动作:
durable=True声明持久拓扑;delivery_mode=2标记持久消息。confirm_delivery()开启发布确认,使本例可以同步获知 Broker 的确认或拒绝。mandatory=True配合 Pika 的返回处理,识别“交换机存在,但没有可路由目标”的情况。
不要用“函数没抛异常”推导消费者已经执行成功。发布确认只覆盖生产者到 Broker 的责任边界。Pika 的阻塞发布在确认模式下会通过 UnroutableError、NackError 等异常报告不同结果,这里不把 basic_publish() 的返回值当布尔成功标志。RabbitMQ 确认机制、Pika 1.4.4 阻塞适配器
还有一个容易忽略的细节:mandatory 判断的是消息是否能路由到目标,并不替你检查所有预期业务订阅都已建立。例如本来需要通知两个服务,只绑定了一个队列,发布仍可能成功;第二个服务不会因为生产者拿到确认就自动收到历史消息。拓扑完整性要作为部署检查的一部分。
示例为便于理解,逐条等待确认后再继续发布。这适合观察状态,不代表 RabbitMQ 的吞吐上限;生产系统若采用批量或异步确认,需要另外维护在途消息和确认关联,不能只删除等待逻辑就宣布优化完成。
连接中断还有一种更难处理的情况:Broker 可能已接收,只是客户端没拿到确认。因此示例不会无限重发;真实业务需要保留稳定的业务事件 ID,并让消费端能够识别重复。消息里的 event_id 只提供识别依据,本例没有实现业务去重。
五、消费者:先处理,再确认
文件:consumer.py。
import argparse
import json
import os
import sys
import time
import pika
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--prefetch", type=int, default=1)
parser.add_argument("--work-seconds", type=float, default=0)
parser.add_argument("--fail-once", action="store_true")
args = parser.parse_args()
if not 1 <= args.prefetch <= 1000:
parser.error("prefetch 必须在 1 到 1000 之间")
if not 0 <= args.work_seconds <= 2:
parser.error("短任务模拟时间必须在 0 到 2 秒之间")
params = pika.URLParameters(os.environ.get(
"AMQP_URL",
"amqp://mq_demo:mq_demo_only_2026@127.0.0.1:5672/%2F",
))
params.heartbeat = 60
params.blocked_connection_timeout = 30
params.socket_timeout = 10
params.stack_timeout = 15
connection = None
try:
connection = pika.BlockingConnection(params)
channel = connection.channel()
channel.exchange_declare("mq.demo", exchange_type="direct", durable=True)
channel.queue_declare("mq.demo.failed", durable=True,
arguments={"x-queue-type": "classic"})
channel.queue_declare("mq.demo.work", durable=True, arguments={
"x-queue-type": "classic",
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "mq.demo.failed",
})
channel.queue_bind("mq.demo.work", "mq.demo", routing_key="work")
channel.basic_qos(prefetch_count=args.prefetch, global_qos=False)
def on_message(ch, method, properties, body):
try:
event = json.loads(body.decode("utf-8"))
if not isinstance(event, dict):
raise ValueError("消息必须是 JSON 对象")
if not isinstance(event.get("event_id"), str) or not event["event_id"]:
raise ValueError("event_id 必须为非空字符串")
if not isinstance(event.get("text"), str):
raise ValueError("text 必须是字符串")
if properties.message_id != event["event_id"]:
raise ValueError("消息属性与正文的 event_id 不一致")
except (UnicodeDecodeError, ValueError) as exc:
print(f"格式错误,转入失败队列: {exc}", flush=True)
# 坏消息不立即放回原队列,避免同一条消息持续自旋。
ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
return
if args.fail_once:
# 抛出后关闭连接,未确认消息可重投;脚本不自动重启。
raise RuntimeError("模拟依赖不可用,先修复再重启消费者")
print(f"开始 pid={os.getpid()} event_id={event['event_id']} "
f"redelivered={method.redelivered}", flush=True)
# 仅模拟不超过 2 秒的短任务,不能直接替换成任意长耗时工作。
time.sleep(args.work_seconds)
print(f"完成 pid={os.getpid()} event_id={event['event_id']}", flush=True)
# 真正接业务时,应在业务事务提交后确认,而非刚收到就确认。
ch.basic_ack(delivery_tag=method.delivery_tag)
channel.basic_consume("mq.demo.work", on_message_callback=on_message,
auto_ack=False)
print(f"消费者已启动 pid={os.getpid()} prefetch={args.prefetch}", flush=True)
channel.start_consuming()
return 0
except KeyboardInterrupt:
return 130
except (pika.exceptions.AMQPError, OSError, RuntimeError) as exc:
print(f"消费者停止,未确认消息等待恢复: {exc}", file=sys.stderr)
return 1
finally:
if connection is not None and connection.is_open:
try:
connection.close()
except pika.exceptions.AMQPError:
pass
if __name__ == "__main__":
sys.exit(main())
auto_ack=False 表示由应用明确确认,prefetch_count=1 则让每个消费者最多持有一条尚未确认的消息。本例处理动作只是打印,不会写数据库,也不能证明业务副作用只发生一次。
失败分成两类处理。格式不正确的消息继续重试也不会自动变好,所以 nack(requeue=False) 将其交给死信流程;临时依赖故障则直接停止进程并关闭连接,让未确认消息等待后续恢复,而不是立刻放回原队列再高速取出。
--work-seconds 只是第三篇观察并发时使用的短暂停顿;--prefetch 允许在同一份脚本中比较接收额度。第一次运行都保留默认值即可,不需要为了“性能好”先把参数拉满。
进程没有自动重连和自动重启,这是明确的示例边界:临时故障发生后先停下来检查原因,再由操作者恢复。真正接入进程守护工具时,还要设置重启退避和告警,否则外部工具也可能把原本避免的自旋重新制造出来。
失败队列用于教学隔离,不是可靠补偿系统。classic queue 的默认死信转发可能在目标不可用等情况下丢失消息;真实关键业务应另行设计可靠转移、告警和人工处理。死信机制及安全边界
为了让第一份脚本可以独立运行,死信参数写在声明里;实际运维更适合用匹配范围清晰的 policy 管理可调整的死信规则,避免每次修改规则都要重新部署客户端。
六、跑通后,再主动制造三个异常
先在终端 A 启动消费者,在终端 B 发布一条消息:
# 终端 A
python consumer.py
# 终端 B
python producer.py --message-id first-note-001
预期生产者输出 Broker 已确认,消费者输出开始、完成及同一个 event_id。管理界面中工作队列会经历 Ready、Unacked 的变化,处理很快时可能看不到中间状态,最终正常消息不应继续留在队列中。
再执行三个小实验,每次只验证一件事:
# 无匹配绑定:应报告没有可路由的目标队列。
python producer.py --routing-key missing
# JSON 格式错误:消费者应将它交给失败队列,而非无限重试。
python producer.py --bad-json
第三个实验先停止其他消费者,再在终端 A 执行 python consumer.py --fail-once,随后在终端 B 发消息。预期该消费者报错退出,关闭连接后消息重新等待处理。修复模拟故障的方法是去掉 --fail-once,重新运行普通消费者;这个参数不会跨进程记录“已经失败过一次”。
可以用只读命令查看队列,而不用在管理界面点击 Get messages;后者可能改变消息投递和确认状态。
docker exec mq-rabbitmq-demo rabbitmqctl list_queues \
name type durable messages_ready messages_unacknowledged consumers
如果出现连接拒绝,先检查容器状态和端口;如果出现认证失败,检查连接地址、虚拟主机和教学账号。持久卷初始化后的账号不会因为单纯修改容器环境变量而自动变更,不要把旧卷里的配置当成空白环境。
七、接入真实业务前还差什么
这份示例已经把“发到哪里”“Broker 是否确认”“业务何时确认”“失败如何退出”表达清楚。它还没有实现数据库与发消息的一致性、幂等落库、可靠重试调度、失败队列告警和多节点容灾,这些都不能从一次正常运行中自动得到。
我更建议先把这几条边界跑明白,再把业务处理函数接进来:收到消息不等于执行成功,关闭连接可能触发重投,设置持久标志也不等于拥有副本。下一篇继续拆开“RabbitMQ 到底怎么存消息”,重点区分拓扑、消息正文、确认和删除。
参考资料与核对说明
核对日期:2026-10-31。版本主线为 RabbitMQ 4.4.0、Pika 1.4.4;当前为待实机验证初稿,没有发布吞吐或可靠性实测结论。
- RabbitMQ Release Information
- Pika 1.4.4 发行页面
- RabbitMQ Exchanges
- RabbitMQ Consumer Acknowledgements and Publisher Confirms
- RabbitMQ Dead Letter Exchanges
- Pika 1.4.4 BlockingConnection 源码与接口注释
验证补充:固定版本 SDK 已在 Python 3.10 隔离环境完成安装、导入和方法签名检查,正文 Python 代码语法检查通过;推荐的 Python 3.12 环境及真实 Broker 收发仍需复验。
记录过程,也留下判断。
← 继续阅读其他文章