20191127 Spring Boot官方文档学习（4.13）

4.13。Messaging

Spring框架为与消息传递系统集成提供了广泛的支持，从使用JmsTemplate简化JMS API到完整的异步接收消息的基础结构。Spring AMQP为高级消息队列协议提供了类似的功能集。Spring Boot还为RabbitTemplate和RabbitMQ 提供了自动配置选项。Spring WebSocket本身就包含对STOMP消息的支持，而Spring Boot通过启动器和少量的自动配置对此提供了支持。Spring Boot还支持Apache Kafka。

4.13.1。JMS

javax.jms.ConnectionFactory接口提供了一种用于创建javax.jms.Connection与JMS代理进行交互的的标准方法。尽管Spring需要ConnectionFactory才能与JMS一起使用，但是您通常不需要自己直接使用它，而可以依赖于更高级别的消息传递抽象。（有关详细信息，请参见Spring Framework参考文档的相关部分。）Spring Boot还会自动配置必要的基础结构，以发送和接收消息。

ActiveMQ支持

当ActiveMQ在类路径中可用时，Spring Boot也可以配置ConnectionFactory。如果存在代理，则将自动启动和配置嵌入式代理（前提是未通过配置指定代理URL）。

如果使用spring-boot-starter-activemq，则提供了连接或嵌入ActiveMQ实例的必要依赖关系，以及与JMS集成的Spring基础结构。

ActiveMQ配置由spring.activemq.*中的外部配置属性控制。例如，您可以在application.properties中声明以下部分：

spring.activemq.broker-url=tcp://192.168.1.210:9876
spring.activemq.user=admin
spring.activemq.password=secret

默认情况下，CachingConnectionFactory 用合理的设置包装原生ConnectionFactory，您可以通过spring.jms.*中的外部配置属性来控制这些设置：

spring.jms.cache.session-cache-size=5

如果您想使用原生池，则可以通过向其添加依赖项org.messaginghub:pooled-jms并对JmsPoolConnectionFactory进行相应的配置来实现，如以下示例所示：

spring.activemq.pool.enabled=true
spring.activemq.pool.max-connections=50

请参阅ActiveMQProperties以获取更多受支持的选项。您还可以注册任意数量的ActiveMQConnectionFactoryCustomizer Bean，以实现更高级的自定义。

默认情况下，ActiveMQ会创建目的地（如果目的地尚不存在），以便根据其提供的名称来解析目的地。

Artemis支持

当Spring Boot 检测到Artemis在类路径中可用时，可以自动配置ConnectionFactory。如果存在代理，则将自动启动和配置嵌入式代理（除非已明确设置mode属性）。支持的模式是embedded（明确表示需要嵌入式代理，并且如果代理在类路径上不可用，则会发生错误）和native（使用netty传输协议连接到代理）。配置后者后，Spring Boot 将使用默认设置配置一个ConnectionFactory连接到在本地计算机上运行的代理。

如果使用spring-boot-starter-artemis，则提供了连接到现有Artemis实例所需的依赖关系，以及与JMS集成的Spring基础结构。添加org.apache.activemq:artemis-jms-server到您的应用程序可以让您使用嵌入式模式。

Artemis配置由spring.artemis.*中的外部配置属性控制。例如，您可以在application.properties中声明以下部分：

spring.artemis.mode=native
spring.artemis.host=192.168.1.210
spring.artemis.port=9876
spring.artemis.user=admin
spring.artemis.password=secret

嵌入代理时，可以选择是否要启用持久性并列出应使其可用的目的地。可以将它们指定为以逗号分隔的列表，以使用默认选项创建它们，或者您可以分别为高级队列和主题配置定义类型为org.apache.activemq.artemis.jms.server.config.JMSQueueConfiguration或org.apache.activemq.artemis.jms.server.config.TopicConfiguration的bean 。

默认情况下，CachingConnectionFactory 用合理的设置包装原生ConnectionFactory，您可以通过spring.jms.*中的外部配置属性来控制这些设置：

spring.jms.cache.session-cache-size=5

如果您想使用原生池，则可以通过向其添加依赖项org.messaginghub:pooled-jms并对JmsPoolConnectionFactory进行相应的配置来实现，如以下示例所示：

spring.artemis.pool.enabled=true
spring.artemis.pool.max-connections=50

请参阅ArtemisProperties以获取更多受支持的选项。

不涉及JNDI查找，并且使用Artemis配置中的name属性或通过配置提供的名称来根据目的地名称解析目的地。

使用JNDI ConnectionFactory

如果您正在应用程序服务器中运行应用程序，则Spring Boot会尝试使用JNDI 查找JMS ConnectionFactory。默认情况下，java:/JmsXA和java:/XAConnectionFactory处于选中状态。如果需要指定替代位置，则可以使用spring.jms.jndi-name属性，如以下示例所示：

spring.jms.jndi-name=java:/MyConnectionFactory

发送信息

Spring JmsTemplate是自动配置的，您可以将其直接注入到您自己的bean中，如以下示例所示：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final JmsTemplate jmsTemplate;

    @Autowired
    public MyBean(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    // ...

}

JmsMessagingTemplate可以以类似方式注入。如果定义了 DestinationResolver或MessageConverter bean，则将其自动关联到自动配置的JmsTemplate。

接收消息

存在JMS基础结构时，可以对任何bean进行@JmsListener注解以创建侦听器端点。如果未定义JmsListenerContainerFactory，则会自动配置一个默认值。如果定义了DestinationResolver或MessageConverter bean，它将自动关联到默认工厂。

默认情况下，默认工厂是事务性的。如果您在存在 JtaTransactionManager 的基础结构中运行，则默认情况下它将与侦听器容器关联。如果不是，则启用 sessionTransacted 标志。在后一种情况下，您可以通过添加@Transactional到侦听器方法（或其委托）将本地数据存储事务与传入消息的处理相关联。这样可以确保本地事务完成后，传入消息得到确认。这还包括在同一JMS会话上执行的发送响应消息。

以下组件在someQueue目的地上创建一个侦听器端点：

@Component
public class MyBean {

    @JmsListener(destination = "someQueue")
    public void processMessage(String content) {
        // ...
    }

}

有关更多详细信息，请参见的@EnableJms。

如果您需要创建更多JmsListenerContainerFactory实例，或者想要覆盖默认实例，Spring Boot提供了一个DefaultJmsListenerContainerFactoryConfigurer，您可以使用与自动配置的相同的设置来初始化DefaultJmsListenerContainerFactory。

例如，以下示例公开了另一个使用特定MessageConverter的工厂：

@Configuration(proxyBeanMethods = false)
static class JmsConfiguration {

    @Bean
    public DefaultJmsListenerContainerFactory myFactory(
            DefaultJmsListenerContainerFactoryConfigurer configurer) {
        DefaultJmsListenerContainerFactory factory =
                new DefaultJmsListenerContainerFactory();
        configurer.configure(factory, connectionFactory());
        factory.setMessageConverter(myMessageConverter());
        return factory;
    }

}

然后，您可以在@JmsListener注解方法中使用工厂：

@Component
public class MyBean {

    @JmsListener(destination = "someQueue", containerFactory="myFactory")
    public void processMessage(String content) {
        // ...
    }

}

4.13.2。AMQP

高级消息队列协议（AMQP）是面向消息中间件的与平台无关的wire-level 协议。Spring AMQP项目将Spring的核心概念应用于基于AMQP的消息传递解决方案的开发。Spring Boot为通过RabbitMQ使用AMQP提供了许多便利，包括spring-boot-starter-amqp“启动器”。

RabbitMQ支持

RabbitMQ是基于AMQP协议的轻量级，可靠，可伸缩和便携式消息代理。Spring使用RabbitMQ通过AMQP协议进行通信。

RabbitMQ配置由spring.rabbitmq.*中的外部配置属性控制。例如，您可以在application.properties中声明以下部分：

spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672
spring.rabbitmq.username=admin
spring.rabbitmq.password=secret

如果上下文中存在ConnectionNameStrategy bean，它将自动用于命名由自动配置的ConnectionFactory创建的连接。请参阅RabbitProperties以获取更多受支持的选项。

发送信息

Spring AmqpTemplate和AmqpAdmin是自动配置的，您可以将它们直接注入到自己的bean中，如以下示例所示：

import org.springframework.amqp.core.AmqpAdmin;
import org.springframework.amqp.core.AmqpTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final AmqpAdmin amqpAdmin;
    private final AmqpTemplate amqpTemplate;

    @Autowired
    public MyBean(AmqpAdmin amqpAdmin, AmqpTemplate amqpTemplate) {
        this.amqpAdmin = amqpAdmin;
        this.amqpTemplate = amqpTemplate;
    }

    // ...

}

RabbitMessagingTemplate可以以类似方式注入。如果定义了MessageConverter bean，它将自动关联到自动配置的 AmqpTemplate。

如有必要，任何定义为org.springframework.amqp.core.Queue bean的对象都会自动用于在RabbitMQ实例上声明相应的队列。

要重试操作，可以在AmqpTemplate上启用重试（例如，在代理连接丢失的情况下）：

spring.rabbitmq.template.retry.enabled=true
spring.rabbitmq.template.retry.initial-interval=2s

默认情况下，重试是禁用的。您也可以通过声明RabbitRetryTemplateCustomizer bean来以编程方式自定义RetryTemplate。

接收消息

存在Rabbit基础结构时，可以对任何bean进行@RabbitListener注解以创建侦听器端点。如果未定义RabbitListenerContainerFactory，则将自动配置SimpleRabbitListenerContainerFactory，并且您可以使用spring.rabbitmq.listener.type属性切换到直接容器。如果定义了MessageConverter或MessageRecoverer bean，将自动与默认工厂关联。

以下示例组件在someQueue队列上创建一个侦听器端点：

@Component
public class MyBean {

    @RabbitListener(queues = "someQueue")
    public void processMessage(String content) {
        // ...
    }

}

有关更多详细信息，请参见的@EnableRabbit。

如果您需要创建更多RabbitListenerContainerFactory实例，或者想要覆盖默认实例，Spring Boot提供了一个SimpleRabbitListenerContainerFactoryConfigurer和DirectRabbitListenerContainerFactoryConfigurer，您可以用来初始化一个自动配置所使用的工厂具有相同的设置的SimpleRabbitListenerContainerFactory和DirectRabbitListenerContainerFactory。

选择哪种容器都没有关系。这两个bean通过自动配置公开。

例如，以下配置类公开了另一个使用特定MessageConverter的工厂：

@Configuration(proxyBeanMethods = false)
static class RabbitConfiguration {

    @Bean
    public SimpleRabbitListenerContainerFactory myFactory(
            SimpleRabbitListenerContainerFactoryConfigurer configurer) {
        SimpleRabbitListenerContainerFactory factory =
                new SimpleRabbitListenerContainerFactory();
        configurer.configure(factory, connectionFactory);
        factory.setMessageConverter(myMessageConverter());
        return factory;
    }

}

然后，您可以在任何带@RabbitListener注解的方法里使用工厂，如下所示：

@Component
public class MyBean {

    @RabbitListener(queues = "someQueue", containerFactory="myFactory")
    public void processMessage(String content) {
        // ...
    }

}

您可以启用重试来处理侦听器引发异常的情况。默认情况下，使用RejectAndDontRequeueRecoverer，但是您可以定义自己的MessageRecoverer。重试用尽后，如果将代理配置为这样做，则消息将被拒绝并被丢弃或路由到死信交换。默认情况下，重试是禁用的。您也可以通过声明RabbitRetryTemplateCustomizer bean来以编程方式自定义RetryTemplate。

默认情况下，如果禁用了重试，并且侦听器抛出异常，则会无限期地重试传递。您可以通过两种方式修改此行为：将defaultRequeueRejected属性设置为false，以便尝试进行零次重新传递，或者抛出AmqpRejectAndDontRequeueException来指示应该拒绝该消息。后者是启用重试并达到最大传递尝试次数时使用的机制。

4.13.3。Apache Kafka支持

通过提供spring-kafka项目的自动配置来支持Apache Kafka。

Kafka配置由spring.kafka.*中的外部配置属性控制。例如，您可以在application.properties中声明以下部分：

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=myGroup

要在启动时创建主题，请添加类型为NewTopic的Bean 。如果该主题已经存在，则将忽略Bean。

请参阅KafkaProperties以获取更多受支持的选项。

发送信息

Spring KafkaTemplate是自动配置的，您可以直接在自己的Bean中注入，如以下示例所示：

@Component
public class MyBean {

    private final KafkaTemplate kafkaTemplate;

    @Autowired
    public MyBean(KafkaTemplate kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    // ...

}

如果定义了spring.kafka.producer.transaction-id-prefix属性，则会自动配置 KafkaTransactionManager。另外，如果定义了RecordMessageConverter bean，它将自动关联到自动配置的KafkaTemplate。

接收消息

存在Apache Kafka基础结构时，可以对任何bean进行@KafkaListener注解以创建侦听器端点。如果尚未定义KafkaListenerContainerFactory，则会使用spring.kafka.listener.*中定义的键自动配置默认值。

以下组件在someTopic主题上创建一个侦听器端点：

@Component
public class MyBean {

    @KafkaListener(topics = "someTopic")
    public void processMessage(String content) {
        // ...
    }

}

如果定义了KafkaTransactionManager bean，它将自动关联到容器工厂。类似地，如果一个ErrorHandler，AfterRollbackProcessor或ConsumerAwareRebalanceListener bean被定义，它被自动关联为默认工厂。

根据侦听器的类型，RecordMessageConverter或BatchMessageConverter bean与默认工厂关联。如果对于批处理侦听器仅存在一个RecordMessageConverter bean，则将其包装在BatchMessageConverter中。

一个自定义ChainedKafkaTransactionManager必须标记@Primary，因为它通常引用自动配置的KafkaTransactionManagerbean。

Kafka Streams

用于Apache Kafka的Spring提供了一个工厂bean来创建StreamsBuilder对象并管理其流的生命周期。只要kafka-streams在类路径上并通过@EnableKafkaStreams注解启用Kafka Streams，Spring Boot就会自动配置所需的KafkaStreamsConfiguration bean 。

启用Kafka Streams意味着必须设置应用程序ID和引导服务器。可以使用spring.kafka.streams.application-id来配置前者，如果未设置，则默认为spring.application.name。后者可以全局设置，也可以仅针对流进行覆盖。

通过专用属性可以使用几个附加属性。可以使用spring.kafka.streams.properties名称空间设置其他任意Kafka属性。

要使用工厂bean，只需将StreamsBuilder连接到您的@Bean，如以下示例所示：

@Configuration(proxyBeanMethods = false)
@EnableKafkaStreams
public static class KafkaStreamsExampleConfiguration {

    @Bean
    public KStream<Integer, String> kStream(StreamsBuilder streamsBuilder) {
        KStream<Integer, String> stream = streamsBuilder.stream("ks1In");
        stream.map((k, v) -> new KeyValue<>(k, v.toUpperCase())).to("ks1Out",
                Produced.with(Serdes.Integer(), new JsonSerde<>()));
        return stream;
    }

}

默认情况下，由StreamBuilder创建的对象管理的流将自动启动。您可以使用spring.kafka.streams.auto-startup属性来自定义此行为。

Kafka的其他属性

自动配置支持的属性显示在“通用应用程序”属性中。请注意，在大多数情况下，这些属性（连字符或驼峰式）直接映射到Apache Kafka点缀的属性。有关详细信息，请参阅Apache Kafka文档。

这些属性的前几个属性适用于所有组件（生产者，使用者，管理员和流），但如果您希望使用不同的值，则可以在组件级别上指定。Apache Kafka指定属性重要性为HIGH，MEDIUM或LOW。Spring Boot自动配置支持所有HIGH重要性属性，一些选定的MEDIUM和LOW属性以及任何没有默认值的属性。

KafkaProperties类直接提供了Kafka支持的属性的子集。如果希望使用不直接支持的其他属性来配置生产者或使用者，请使用以下属性：

spring.kafka.properties.prop.one=first
spring.kafka.admin.properties.prop.two=second
spring.kafka.consumer.properties.prop.three=third
spring.kafka.producer.properties.prop.four=fourth
spring.kafka.streams.properties.prop.five=fifth

这会将通用的Kafka属性prop.one设置为first（适用于生产者，消费者和管理员），将admin属性prop.two 设置为second，将消费者属性prop.three设置为third，将生产者属性prop.four设置为fourth，并将stream属性prop.five设置为fifth。

您还可以按如下方式配置Spring Kafka JsonDeserializer：

spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.value.default.type=com.example.Invoice
spring.kafka.consumer.properties.spring.json.trusted.packages=com.example,org.acme

同样，您可以禁用在标头中发送类型信息的JsonSerializer默认行为：

spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.producer.properties.spring.json.add.type.headers=false

以这种方式设置的属性将覆盖Spring Boot显式支持的任何配置项。

使用嵌入式Kafka进行测试

Spring for Apache Kafka提供了一种使用嵌入式Apache Kafka代理测试项目的便捷方法。要使用此功能，请在测试类上使用在spring-kafka-test模块中的@EmbeddedKafka注解。有关更多信息，请参阅Spring for Apache Kafka 参考手册。

要使Spring Boot自动配置与上述嵌入式Apache Kafka代理一起使用，您需要将嵌入式代理地址（由EmbeddedKafkaBroker填充）的系统属性重新映射到Apache Kafka的Spring Boot配置属性中。有几种方法可以做到这一点：

在测试类中，提供系统属性以将嵌入式代理地址映射到spring.kafka.bootstrap-servers：

static {
    System.setProperty(EmbeddedKafkaBroker.BROKER_LIST_PROPERTY, "spring.kafka.bootstrap-servers");
}

在@EmbeddedKafka注解上配置属性名称：

@EmbeddedKafka(topics = "someTopic",
        bootstrapServersProperty = "spring.kafka.bootstrap-servers")

在配置属性中使用占位符：

spring.kafka.bootstrap-servers=${spring.embedded.kafka.brokers}