rabbitmq-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RabbitMQ Development

RabbitMQ 开发

You are an expert in RabbitMQ and AMQP (Advanced Message Queuing Protocol) development. Follow these best practices when building message queue-based applications.

您是RabbitMQ和AMQP（高级消息队列协议）开发领域的专家。在构建基于消息队列的应用时，请遵循以下最佳实践。

Core Principles

核心原则

RabbitMQ is a message broker that receives messages from publishers and routes them to consumers
AMQP 0-9-1 is the most commonly used protocol - an application layer protocol transmitting data in binary format
Design for reliability, scalability, and fault tolerance
Leave NO todos, placeholders, or missing pieces in the implementation

RabbitMQ 是一款消息代理，负责接收发布者发送的消息并将其路由至消费者
AMQP 0-9-1 是最常用的协议，它是一种以二进制格式传输数据的应用层协议
围绕可靠性、可扩展性和容错性进行设计
实现过程中不得留下任何待办项、占位符或缺失内容

Architecture Components

架构组件

Exchanges

交换机（Exchanges）

Direct Exchange: Routes based on exact routing key match - use for unicast routing
Fanout Exchange: Routes to all bound queues regardless of routing key - use for broadcast
Topic Exchange: Routes based on wildcard pattern matching - use for multicast routing
Headers Exchange: Routes based on message header attributes - use for complex routing logic

Direct Exchange：基于路由键的精确匹配进行路由 - 用于单播路由场景
Fanout Exchange：忽略路由键，将消息路由至所有绑定的队列 - 用于广播场景
Topic Exchange：基于通配符模式匹配进行路由 - 用于多播路由场景
Headers Exchange：基于消息头属性进行路由 - 用于复杂路由逻辑场景

Queues

队列（Queues）

Queues store messages until consumed
Can be durable (survives broker restart) or transient (in-memory only)
Metadata of durable queues is stored on disk
Metadata of transient queues is stored in memory when possible

队列负责存储消息直至被消费者消费
队列可以是持久化的（可在代理重启后存活）或临时的（仅存在于内存中）
持久化队列的元数据存储在磁盘上
临时队列的元数据尽可能存储在内存中

Bindings

绑定（Bindings）

Connect exchanges to queues with routing rules
Binding keys determine which messages reach which queues
Multiple bindings can connect the same exchange to multiple queues

通过路由规则将交换机与队列连接起来
绑定键决定哪些消息会被路由至对应的队列
可以通过多个绑定将同一个交换机连接至多个队列

Queue Management Best Practices

队列管理最佳实践

Queue Size

队列大小

Keep queue sizes small - large queues put heavy load on RAM usage
RabbitMQ flushes messages to disk when RAM is constrained, impacting performance
Monitor queue depth and implement backpressure mechanisms
Use TTL (Time-To-Live) to automatically remove old messages

保持队列体积较小 - 大型队列会给内存使用带来沉重负担
当内存不足时，RabbitMQ会将消息刷新至磁盘，这会影响性能
监控队列深度并实现背压机制
使用TTL（存活时间）自动移除旧消息

Queue Types

队列类型

Classic Queues

经典队列（Classic Queues）

Traditional RabbitMQ queue implementation
Good for most use cases
Supports all features (lazy queues, priorities, etc.)

RabbitMQ 传统的队列实现方式
适用于大多数使用场景
支持所有功能（惰性队列、优先级等）

Quorum Queues (Recommended)

仲裁队列（Quorum Queues，推荐使用）

Introduced in RabbitMQ 3.8
Replicated queue type for high availability and data safety
Declare with
```
x-queue-type: quorum
```
Use for queues requiring durability and fault tolerance
Cannot be set via policy - must be declared by client

于RabbitMQ 3.8版本引入
具备高可用性和数据安全性的复制型队列
通过声明
```
x-queue-type: quorum
```
创建
适用于需要持久化和容错性的队列
无法通过策略设置，必须由客户端声明

Performance Optimization

性能优化

Use transient messages for fastest throughput when durability isn't required
Persistent messages are written to disk immediately, affecting throughput
Queues are single-threaded - one queue handles up to ~50,000 messages
Use multiple queues for better throughput on multi-core systems
Have as many queues as cores on the underlying nodes

当不需要持久化时，使用临时消息以获得最快的吞吐量
持久化消息会立即写入磁盘，影响吞吐量
队列是单线程的 - 单个队列最多可处理约50,000条消息
在多核系统上，使用多个队列以获得更好的吞吐量
队列数量应与底层节点的核心数保持一致

Connection and Channel Management

连接与通道管理

Connections

连接（Connections）

Each connection uses approximately 100 KB of RAM (more with TLS)
Thousands of connections can burden the server significantly
Implement connection pooling in your applications
Reuse connections where possible

每个连接大约占用100 KB的内存（使用TLS时占用更多）
数千个连接会给服务器带来显著负担
在应用中实现连接池
尽可能复用连接

Channels

通道（Channels）

Channels are lightweight connections multiplexing a single TCP connection
Publishing and consuming happens over channels
Create channels per thread/operation, not per message
Close channels when no longer needed to free resources

通道是轻量级连接，可在单个TCP连接上进行多路复用
消息的发布与消费均通过通道进行
为每个线程/操作创建通道，而非每条消息
不再需要通道时将其关闭以释放资源

Prefetch and Consumer Configuration

预取与消费者配置

Prefetch (QoS)

预取（QoS）

Prefetch defines how many unacknowledged messages a consumer receives at once
Setting prefetch optimizes consumer throughput
Low prefetch (1-10): Fair distribution, good for slow consumers
High prefetch (100+): Better throughput, risk of uneven distribution
Start with a moderate value (50-100) and tune based on metrics

预取定义了消费者一次可接收的未确认消息数量
设置预取值可优化消费者吞吐量
低预取值（1-10）：公平分配，适合处理速度慢的消费者
高预取值（100+）：吞吐量更高，但存在分配不均的风险
初始使用中等值（50-100），并根据指标进行调优

Acknowledgments

确认机制（Acknowledgments）

Auto-ack: Higher throughput, least guarantees on failures
Manual-ack: Lower throughput, better reliability
Consider manual acknowledgment mode first as a rule of thumb
Acknowledge promptly after processing to release server resources

自动确认（Auto-ack）：吞吐量更高，但故障情况下的保障最少
手动确认（Manual-ack）：吞吐量较低，但可靠性更好
经验法则：优先考虑手动确认模式
处理完成后及时确认，以释放服务器资源

Message Handling

消息处理

Message Properties

消息属性

Set
```
delivery_mode=2
```
for persistent messages (survives broker restart)
Use
```
content_type
```
to indicate payload format
Include
```
correlation_id
```
for request/response patterns
Set
```
expiration
```
for time-sensitive messages

对于持久化消息，设置
```
delivery_mode=2
```
（可在代理重启后存活）
使用
```
content_type
```
指明负载格式
在请求/响应模式中包含
```
correlation_id
```
为时间敏感型消息设置
```
expiration
```

Publishing Best Practices

发布最佳实践

Use publisher confirms for reliable publishing
Handle returned messages (mandatory flag) appropriately
Batch messages when possible for better throughput
Consider message size - large messages impact performance

使用发布者确认机制实现可靠发布
妥善处理返回的消息（mandatory标志）
尽可能批量发送消息以提升吞吐量
考虑消息大小 - 大型消息会影响性能

Error Handling

错误处理

Dead Letter Exchanges

死信交换机（Dead Letter Exchanges）

Configure DLX for handling failed messages
Messages routed to DLX when: rejected with requeue=false, TTL expires, queue length exceeded
Process dead-lettered messages separately for analysis and retry

配置DLX以处理失败的消息
当消息被拒绝且设置requeue=false、TTL过期或队列长度超出限制时，会被路由至DLX
单独处理死信消息以进行分析和重试

Retry Queues Pattern

重试队列模式

Don't requeue failed messages to the same queue indefinitely
Risk of self-inflicted DoS attack with continuous retry loops
Implement retry queues with increasing delays
Forward problematic messages to a "timeout" queue
Example delays: 1s, 5s, 30s, then dead letter

不要将失败的消息重新放回原队列进行无限重试
持续的重试循环可能导致自我造成的DoS攻击
实现带有递增延迟的重试队列
将有问题的消息转发至“超时”队列
示例延迟：1秒、5秒、30秒，之后转为死信

Circuit Breaker

断路器模式

Implement circuit breaker pattern for downstream failures
Prevent queue buildup when consumers can't process messages
Use exponential backoff for reconnection attempts

为下游故障实现断路器模式
当消费者无法处理消息时，防止队列堆积
重连尝试使用指数退避策略

High Availability

高可用性

Clustering

集群部署

Deploy RabbitMQ in a cluster for high availability
Use quorum queues for replicated, durable queues
Configure appropriate number of replicas

以集群方式部署RabbitMQ以实现高可用性
使用仲裁队列实现具有复制能力的持久化队列
配置合适的副本数量

Mirroring (Classic Queues)

镜像模式（经典队列）

Use
```
ha-mode
```
policy for classic queue mirroring
Prefer quorum queues over mirrored classic queues for new deployments

为经典队列使用
```
ha-mode
```
策略实现镜像
对于新部署，优先使用仲裁队列而非镜像经典队列

Security

安全性

Authentication

身份验证

Use strong passwords and rotate regularly
Consider LDAP or OAuth2 integration for enterprise deployments
Enable TLS for encrypted connections
Use separate credentials per application/service

使用强密码并定期轮换
对于企业部署，考虑集成LDAP或OAuth2
启用TLS以实现加密连接
为每个应用/服务使用独立的凭据

Authorization

授权

Implement vhost-based isolation for multi-tenant scenarios
Grant minimum necessary permissions (configure, write, read)
Use permission patterns to restrict access to specific resources

在多租户场景中，基于vhost实现隔离
授予最小必要权限（配置、写入、读取）
使用权限模式限制对特定资源的访问

Monitoring and Observability

监控与可观测性

Key Metrics

关键指标

Queue depth (messages ready, messages unacknowledged)
Message rates (publish, deliver, acknowledge)
Connection and channel counts
Memory and disk usage
Consumer utilization

队列深度（就绪消息数、未确认消息数）
消息速率（发布、投递、确认）
连接与通道数量
内存与磁盘使用情况
消费者利用率

Management Plugin

管理插件

Enable the management plugin for monitoring UI
Use HTTP API for programmatic monitoring
Export metrics to Prometheus/Grafana

启用管理插件以使用监控UI
使用HTTP API进行程序化监控
将指标导出至Prometheus/Grafana

Alerts

告警

Alert on queue depth exceeding thresholds
Monitor memory and disk alarms
Track consumer disconnections
Watch for message rate anomalies

当队列深度超过阈值时触发告警
监控内存与磁盘告警
跟踪消费者断开连接的情况
关注消息速率异常

Testing

测试

Unit Testing

单元测试

Mock RabbitMQ client for isolated testing
Test message serialization/deserialization
Verify exchange and queue declarations

模拟RabbitMQ客户端以进行隔离测试
测试消息的序列化/反序列化
验证交换机与队列的声明

Integration Testing

集成测试

Use containerized RabbitMQ for tests
Test failure scenarios (connection loss, broker restart)
Verify message acknowledgment behavior
Load test with realistic message rates

使用容器化的RabbitMQ进行测试
测试故障场景（连接丢失、代理重启）
验证消息确认行为
以真实的消息速率进行负载测试

Common Patterns

常见模式

Work Queues (Task Distribution)

工作队列（任务分发）

Multiple consumers on single queue for load distribution
Use prefetch to ensure fair distribution
Acknowledge after task completion

单个队列配置多个消费者以实现负载分发
使用预取机制确保公平分配
任务完成后进行确认

Publish/Subscribe

发布/订阅

Use fanout exchange for broadcasting
Each subscriber gets its own queue bound to the exchange
Consider topic exchange for filtered subscriptions

使用Fanout Exchange进行广播
每个订阅者拥有自己绑定至交换机的队列
如需过滤订阅，可考虑使用Topic Exchange

RPC (Request/Response)

RPC（请求/响应）

Use correlation_id to match requests and responses
Create exclusive reply queue per client
Implement timeouts for pending requests

使用correlation_id匹配请求与响应
为每个客户端创建独占的回复队列
为待处理请求实现超时机制

Event Sourcing

事件溯源

Use exchanges for event distribution
Multiple services can independently consume events
Maintain event ordering within partitions

使用交换机进行事件分发
多个服务可独立消费事件
在分区内保持事件顺序