跳到主要内容
版本:4.1.1

注解驱动的监听端点

Doubao 中英对照 Annotation-driven Listener Endpoints

异步接收消息的最简单方式是使用注解驱动的监听端点基础架构。简而言之,它让你把一个受管 bean 的方法暴露为 Redis 监听端点。下例展示了如何使用它:

@Component
public class MyService {

@RedisListener(topic = "my-channel")
public void processOrder(String data) { ... }
}

上例的思路是:每当通过 my-channel 通道收到消息时,就会相应地调用 processOrder 方法(在本例中,传入的是 Redis Pub/Sub 消息的内容,类似于 MessageListenerAdapter 所提供的方式)。

注解端点基础架构会在幕后为每个被注解的方法创建一个消息监听器,并注册到 RedisMessageListenerContainer。端点不会注册到应用上下文中,但可以通过使用 RedisListenerEndpointRegistry bean 方便地定位它们,以便进行管理。

提示

@RedisListener 是一个可重复注解,因此你可以通过在方法上添加额外的 @RedisListener 声明,把多个 Redis 主题(通道或模式)关联到同一个方法。

启用监听端点注解​

要启用对 @RedisListener 注解的支持,你可以在某个 @Configuration 类上添加 @EnableRedisListeners,如下例所示:

@Configuration
@EnableRedisListeners
public class RedisConfiguration {

@Bean
public RedisMessageListenerContainer redisMessageListenerContainer(RedisConnectionFactory connectionFactory) {

RedisMessageListenerContainer factory = new RedisMessageListenerContainer();
factory.setConnectionFactory(connectionFactory);
return factory;
}
}

你可以通过实现 RedisListenerConfigurer 接口来自定义监听端点注册器。细节和示例请参见实现了 RedisListenerConfigurer 的类的 javadoc。

编程式端点注册​

RedisListenerEndpoint 提供了 Redis 端点的模型,并负责为该模型配置容器。除了由 RedisListener 注解检测到的端点之外,该基础架构还让你可以以编程方式配置端点。下例展示了如何这样做:

@Configuration
@EnableRedisListeners
public class AppConfig implements RedisListenerConfigurer {

@Override
public void configureRedisListeners(RedisListenerEndpointRegistrar registrar) {
SimpleRedisListenerEndpoint endpoint = new SimpleRedisListenerEndpoint();
endpoint.setId("myRedisEndpoint");
endpoint.setTopic("my-channel");
endpoint.setMessageListener((message, pattern) -> {
// processing
});
registrar.registerEndpoint(endpoint);
}
}

在上面的示例中,我们使用了 SimpleRedisListenerEndpoint,它提供要调用的实际 MessageListener。不过,你也可以构建自己的端点变体来描述自定义的调用机制。

请注意,你可以完全不使用 @RedisListener,而只通过 RedisListenerConfigurer 以编程方式注册你的端点。

注解端点方法签名​

到目前为止,我们在端点中注入的是一个简单的 String,但它实际上可以具有非常灵活的方法签名。下例中,我们把它改写为注入带请求头的 Order:

@Component
public class MyService {

@RedisListener("my-order-channels*")
public void processOrder(Order order, @Header("pattern") Topic pattern) {
...
}
}

你可以在 Redis 监听端点中注入的主要元素如下:

  • 表示传入 Redis 消息的 org.springframework.messaging.Message。请注意,该消息持有请求头(由 PubSubHeaders 定义)。
  • 用 @Header 注解的方法参数,用于提取特定的请求头值。由于 Redis Pub/Sub 消息只由消息体组成,因此诸如与消息匹配的主题或模式之类的请求头值会作为请求头被合成添加。
  • 用 @Headers 注解的参数,它还必须可赋值给 java.util.Map,以便访问所有请求头。
  • 未被注解、且不属于受支持类型的元素会被视为载荷。你可以通过用 @Payload 注解该参数来显式声明。你还可以通过额外添加 @Valid 来开启校验。

注入 Spring 的 Message 抽象这一能力,对于在不依赖传输层专用 API 的情况下利用传输层专用消息中存储的全部信息尤为有用。下例展示了如何这样做:

@RedisListener("my-channel")
public void processOrder(Message<byte[]> order) { ... }

方法参数的处理由 DefaultMessageHandlerMethodFactory 提供,你可以进一步自定义它以支持额外的方法参数。基于注解的端点支持灵活的消息转换,这由 RedisMessageConverters 连同一组默认转换器提供,涵盖 String、字节数组和 JSON(如果 classpath 上存在受支持的库)。如果你希望自定义消息转换,可以通过实现 RedisListenerConfigurer 并重写 configureMessageConverters 方法来完成,如下例所示:

@Configuration
@EnableRedisListeners
public class AppConfig implements RedisListenerConfigurer {

@Override
public void configureMessageConverters(RedisMessageConverters.Builder builder) {
builder.withStringConverter(StandardCharsets.UTF_8)
.addCustomConverter(new JdkSerializationRedisSerializer());
}
}

RedisMessageConverters 默认注册以下转换器:

  • StringMessageConverter
  • ByteArrayMessageConverter
  • JSON 转换器(如果 classpath 上存在受支持的库,例如 Jackson、Gson、JSON-B 或 Kotlin Serialization)
备注

RedisMessageConverters 使用 Spring Data Redis 的 RedisSerializers` 进行 JSON 序列化。其 JSON 序列化格式和行为可能与 Spring Messaging 的 JacksonJsonMessageConverter 略有不同。如果你希望使用 Spring Messaging 的变体,请通过 Builder.addCustomConverter(MessageConverter) 配置所需的转换器。

@RedisListener(consumes) 在使用不同消息转换器来选择合适的转换器时,有助于指明期望的内容类型。下例假设按前一个示例完成了注册,展示了为 JdkSerializationRedisSerializer 转换器进行的转换器选择:

@RedisListener(topic = "my-channel", consumes = JdkSerializerMessageConverter.APPLICATION_JAVA_SERIALIZED_OBJECT_VALUE)
public void processOrder(Person person) { ... }
备注

对于未指定内容类型的注解端点,其载荷参数转换将由第一个能够读取消息载荷的转换器处理。

如果你需要对方法参数解析有更多控制,还可以通过 RedisListenerConfigurer 配置一个自定义的 MessageHandlerMethodFactory。你也可以在那里自定义转换和校验支持。

例如,如果我们想在处理 Order 之前确保它是合法的,可以用 @Valid 注解载荷并配置必要的校验器,如下例所示:

@Configuration
@EnableRedisListeners
public class AppConfig implements RedisListenerConfigurer {

@Override
public void configureRedisListeners(RedisListenerEndpointRegistrar registrar) {
registrar.setMessageHandlerMethodFactory(myRedisHandlerMethodFactory());
}

@Bean
public DefaultMessageHandlerMethodFactory myRedisHandlerMethodFactory() {
DefaultMessageHandlerMethodFactory factory = new DefaultMessageHandlerMethodFactory();
factory.setValidator(myValidator());
return factory;
}
}