AMQP
高级消息队列协议 (AMQP) 是一个与平台无关的线级协议,用于面向消息的中间件。Spring AMQP 项目将 Spring 核心概念应用于基于 AMQP 的消息解决方案的开发。Spring Boot 为通过 RabbitMQ 使用 AMQP 提供多种便利,包括 spring-boot-starter-amqp
“Starter”。
The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for message-oriented middleware.
The Spring AMQP project applies core Spring concepts to the development of AMQP-based messaging solutions.
Spring Boot offers several conveniences for working with AMQP through RabbitMQ, including the spring-boot-starter-amqp
“Starter”.
RabbitMQ Support
RabbitMQ 是一个基于 AMQP 协议的轻量级、可靠、可扩展且可移植的消息代理。Spring 使用 RabbitMQ 通过 AMQP 协议实现通信。
RabbitMQ is a lightweight, reliable, scalable, and portable message broker based on the AMQP protocol. Spring uses RabbitMQ to communicate through the AMQP protocol.
RabbitMQ 配置由 spring.rabbitmq.*
中的外部配置属性控制。例如,您可以在 application.properties
中声明以下部分:
RabbitMQ configuration is controlled by external configuration properties in spring.rabbitmq.*
.
For example, you might declare the following section in application.properties
:
spring: rabbitmq: host: "localhost" port: 5672 username: "admin" password: "secret"
或者,您可以使用 addresses
属性配置相同的连接:
Alternatively, you could configure the same connection using the addresses
attribute:
spring: rabbitmq: addresses: "amqp://admin:secret@localhost"
以这种方式指定地址时,将忽略 |
When specifying addresses that way, the |
有关更多受支持的基于属性的配置选项,请参阅 {code-spring-boot-autoconfigure-src}/amqp/RabbitProperties.java[RabbitProperties
]。要配置 Spring AMQP 使用的 RabbitMQ ConnectionFactory
的更低级别详细信息,请定义一个 ConnectionFactoryCustomizer
bean。
See {code-spring-boot-autoconfigure-src}/amqp/RabbitProperties.java[RabbitProperties
] for more of the supported property-based configuration options.
To configure lower-level details of the RabbitMQ ConnectionFactory
that is used by Spring AMQP, define a ConnectionFactoryCustomizer
bean.
如果上下文中存在 ConnectionNameStrategy
bean,它将被自动用于命名由自动配置的 CachingConnectionFactory
创建的连接。
If a ConnectionNameStrategy
bean exists in the context, it will be automatically used to name connections created by the auto-configured CachingConnectionFactory
.
要对 RabbitTemplate
进行全应用程序的附加自定义,请使用一个 RabbitTemplateCustomizer
bean。
To make an application-wide, additive customization to the RabbitTemplate
, use a RabbitTemplateCustomizer
bean.
有关更多详细信息,请参见 Understanding AMQP, the protocol used by RabbitMQ。 |
See Understanding AMQP, the protocol used by RabbitMQ for more details. |
Sending a Message
Spring 的 AmqpTemplate
和 AmqpAdmin
已自动配置,您可以将它们直接自动装配到您自己的 bean 中,如下例所示:
Spring’s AmqpTemplate
and AmqpAdmin
are auto-configured, and you can autowire them directly into your own beans, as shown in the following example:
{url-spring-amqp-javadoc}/rabbit/core/RabbitMessagingTemplate.html[ |
{url-spring-amqp-javadoc}/rabbit/core/RabbitMessagingTemplate.html[ |
如果需要,作为 bean 定义的任何 org.springframework.amqp.core.Queue
都将自动用于在 RabbitMQ 实例上声明一个对应的队列。
If necessary, any org.springframework.amqp.core.Queue
that is defined as a bean is automatically used to declare a corresponding queue on the RabbitMQ instance.
要重试操作,你可以启用 AmqpTemplate
上的重试(例如,在代理连接丢失时):
To retry operations, you can enable retries on the AmqpTemplate
(for example, in the event that the broker connection is lost):
spring: rabbitmq: template: retry: enabled: true initial-interval: "2s"
重试默认处于禁用状态。你也可以通过声明一个 RabbitRetryTemplateCustomizer
bean 以编程方式定制 RetryTemplate
。
Retries are disabled by default.
You can also customize the RetryTemplate
programmatically by declaring a RabbitRetryTemplateCustomizer
bean.
如果您需要创建更多 RabbitTemplate
实例,或者您希望覆盖默认值,Spring Boot 提供了一个 RabbitTemplateConfigurer
bean,您可以使用它来初始化一个 RabbitTemplate
,其具有与自动配置所用的工厂相同的设置。
If you need to create more RabbitTemplate
instances or if you want to override the default, Spring Boot provides a RabbitTemplateConfigurer
bean that you can use to initialize a RabbitTemplate
with the same settings as the factories used by the auto-configuration.
Sending a Message To A Stream
若要向特定流发送消息,请按以下示例所示指定流的名称:
To send a message to a particular stream, specify the name of the stream, as shown in the following example:
spring: rabbitmq: stream: name: "my-stream"
如果已经定义了一个 MessageConverter
、StreamMessageConverter`或 `ProducerCustomizer
bean,那么它会自动关联到自动配置的 RabbitStreamTemplate
。
If a MessageConverter
, StreamMessageConverter
, or ProducerCustomizer
bean is defined, it is associated automatically to the auto-configured RabbitStreamTemplate
.
如果您需要创建更多 RabbitStreamTemplate
实例,或者您希望覆盖默认值,Spring Boot 提供了一个 RabbitStreamTemplateConfigurer
bean,您可以使用它来初始化一个 RabbitStreamTemplate
,其具有与自动配置所用的工厂相同的设置。
If you need to create more RabbitStreamTemplate
instances or if you want to override the default, Spring Boot provides a RabbitStreamTemplateConfigurer
bean that you can use to initialize a RabbitStreamTemplate
with the same settings as the factories used by the auto-configuration.
Receiving a Message
当 Rabbit 基础设施存在时,可以通过 @RabbitListener`对任何 bean 进行注释以创建侦听器端点。如果尚未定义 `RabbitListenerContainerFactory
,将自动配置一个默认的 SimpleRabbitListenerContainerFactory
,并且您可以使用 configprop:spring.rabbitmq.listener.type[] 属性切换到直接容器。如果已经定义了一个 MessageConverter
或 MessageRecoverer
bean,它将自动关联到默认工厂。
When the Rabbit infrastructure is present, any bean can be annotated with @RabbitListener
to create a listener endpoint.
If no RabbitListenerContainerFactory
has been defined, a default SimpleRabbitListenerContainerFactory
is automatically configured and you can switch to a direct container using the configprop:spring.rabbitmq.listener.type[] property.
If a MessageConverter
or a MessageRecoverer
bean is defined, it is automatically associated with the default factory.
以下示例组件在 someQueue
队列上创建一个侦听器端点:
The following sample component creates a listener endpoint on the someQueue
queue:
有关更多详细信息,请参见 {url-spring-amqp-javadoc}/rabbit/annotation/EnableRabbit.html[ |
See {url-spring-amqp-javadoc}/rabbit/annotation/EnableRabbit.html[the Javadoc of |
如果您需要创建更多 RabbitListenerContainerFactory
实例,或者您希望覆盖默认值,Spring Boot 提供了一个 SimpleRabbitListenerContainerFactoryConfigurer
和一个 DirectRabbitListenerContainerFactoryConfigurer
,您可以使用它们来初始化一个 SimpleRabbitListenerContainerFactory
和一个 DirectRabbitListenerContainerFactory
,其具有与自动配置所用的工厂相同的设置。
If you need to create more RabbitListenerContainerFactory
instances or if you want to override the default, Spring Boot provides a SimpleRabbitListenerContainerFactoryConfigurer
and a DirectRabbitListenerContainerFactoryConfigurer
that you can use to initialize a SimpleRabbitListenerContainerFactory
and a DirectRabbitListenerContainerFactory
with the same settings as the factories used by the auto-configuration.
无论您选择了哪种容器类型,都不重要。这两个 bean 都由自动配置公开。 |
It does not matter which container type you chose. Those two beans are exposed by the auto-configuration. |
例如,以下配置类公开另一个使用特定 MessageConverter
的工厂:
For instance, the following configuration class exposes another factory that uses a specific MessageConverter
:
然后,您可以在任何带有 @RabbitListener
注释的方法中使用该工厂,如下所示:
Then you can use the factory in any @RabbitListener
-annotated method, as follows:
您可以启用重试以处理侦听器抛出异常的情况。默认情况下,使用 RejectAndDontRequeueRecoverer
,但您可以自定义自己的 MessageRecoverer
。当重试用尽时,消息会被拒绝,如果代理配置了这样做,则会丢弃该消息或将其路由到死信交换。默认情况下,重试处于禁用状态。您也可以通过声明一个 RabbitRetryTemplateCustomizer
bean 以编程方式定制 RetryTemplate
。
You can enable retries to handle situations where your listener throws an exception.
By default, RejectAndDontRequeueRecoverer
is used, but you can define a MessageRecoverer
of your own.
When retries are exhausted, the message is rejected and either dropped or routed to a dead-letter exchange if the broker is configured to do so.
By default, retries are disabled.
You can also customize the RetryTemplate
programmatically by declaring a RabbitRetryTemplateCustomizer
bean.
默认情况下,如果禁用了重试,并且侦听器抛出了异常,则会无限期地重试传递。您可以通过两种方式修改此行为:将 defaultRequeueRejected
属性设置为 false
,以便尝试零次重新传递,或者抛出一个 AmqpRejectAndDontRequeueException
以指示该消息应该被拒绝。在启用重试并且达到最大传递尝试次数时,后者是所用的机制。
By default, if retries are disabled and the listener throws an exception, the delivery is retried indefinitely.
You can modify this behavior in two ways: Set the defaultRequeueRejected
property to false
so that zero re-deliveries are attempted or throw an AmqpRejectAndDontRequeueException
to signal the message should be rejected.
The latter is the mechanism used when retries are enabled and the maximum number of delivery attempts is reached.