Skip to content

starter-mq ​

1. 职责 ​

在 Redis 之上做一套「够用」的消息抽象:Channel 消息是 Pub/Sub 广播(发出去就不管有没有人收),Stream 消息是带消费组的队列(能 ACK、能补偿未确认消息、能裁剪历史)。

它还统一了消息的序列化(JSON)与拦截器(RedisMessageInterceptor,租户透传就挂在这里),并给 RabbitMQ 补一个 Jackson2JsonMessageConverter。

它不解决:事务消息、延迟消息、消息幂等与失败重试(AbstractRedisStreamMessageListener 的 TODO 里明确列了这四项没做)、RocketMQ/Kafka 的完整封装(只有租户相关的 hook)。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-mq/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
RedisMQTemplate发送入口:Channel 用 convertAndSend,Stream 用 opsForStream().add 并返回 RecordIdmq/redis/core/RedisMQTemplate.java
RedisMessageInterceptor4 个默认方法:sendMessageBefore/After、consumeMessageBefore/Aftermq/redis/core/interceptor/RedisMessageInterceptor.java
AbstractRedisMessage消息基类:headers(Map<String,String>)+ getHeader/addHeadermq/redis/core/message/AbstractRedisMessage.java
AbstractRedisChannelMessage / …Listener<T>Pub/Sub:channel 名默认取类简名;监听器无参构造里反射拿泛型与 channelmq/redis/core/pubsub/
AbstractRedisStreamMessage / …Listener<T>Stream:streamKey 默认取类简名;消费组默认 ${spring.application.name}mq/redis/core/stream/
PmforgeRedisMQProducerAutoConfiguration建 RedisMQTemplate 并把所有拦截器挂上mq/redis/config/
PmforgeRedisMQConsumerAutoConfiguration建 RedisMessageListenerContainer(Channel)与 StreamMessageListenerContainer(Stream),并注册两个补偿 Jobmq/redis/config/
RedisPendingMessageResendJob每分钟(cron = "35 * * * * ?")把 pending ≥ 5 分钟的消息重投mq/redis/core/job/
RedisStreamMessageCleanupJob每小时(cron = "0 0 * * * ?")XTRIM 保留最近 10000 条mq/redis/core/job/
PmforgeRabbitMQAutoConfiguration@ConditionalOnClass(RabbitTemplate),注册 Jackson2JsonMessageConvertermq/rabbitmq/config/

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeRedisMQProducerAutoConfiguration@AutoConfiguration(after = PmforgeRedisAutoConfiguration.class)RedisMQTemplate(StringRedisTemplate, List<RedisMessageInterceptor>),构造时逐个 addInterceptor
PmforgeRedisMQConsumerAutoConfiguration@EnableScheduling + after = PmforgeRedisAutoConfiguration.classRedisMessageListenerContainer(@ConditionalOnBean(AbstractRedisChannelMessageListener.class),按 ChannelTopic 注册);StreamMessageListenerContainer(@ConditionalOnBean(AbstractRedisStreamMessageListener.class),initMethod="start");两个补偿 Job(同样按 Stream 监听器存在与否)
PmforgeRabbitMQAutoConfiguration@ConditionalOnClass(name = "org.springframework.amqp.rabbit.core.RabbitTemplate")MessageConverter = Jackson2JsonMessageConverter

Stream 容器的细节:batchSize(10)、targetType(String.class)、consumerName = 本机IP@PID、autoAcknowledge(false)、cancelOnError(t -> false);启动前 checkRedisVersion,主版本 < 5 直接抛 IllegalStateException(提示参考 Redis 安装文档)。

4. 配置项 ​

前缀键默认值说明
—无—本模块没有 @ConfigurationProperties
spring.application.name—pmforge-server(示例)Stream 消费组名默认取它
spring.data.redis—由 Redisson/Spring Boot 提供连接配置
spring.rabbitmq / rocketmq / spring.kafka—第三方 starter 的配置仅当引入对应依赖时生效

消息类名即路由键(channel / streamKey 默认为类简名),所以改类名等于改主题,生产上要显式覆写 getChannel() / getStreamKey()。

5. 扩展点 ​

  • 加一条广播消息:继承 AbstractRedisChannelMessage + 写 AbstractRedisChannelMessageListener<MyMessage> 实现类(@Component),channel 自动注册。
  • 加一条队列消息:继承 AbstractRedisStreamMessage + AbstractRedisStreamMessageListener<MyMessage>,onMessage 里 acknowledge(基类已封装)后返回 Success。
  • 拦截器:实现 RedisMessageInterceptor,在 sendMessageBefore 加 header、consumeMessageBefore 恢复上下文——biz-tenant 的 TenantRedisMessageInterceptor 就是范例。
  • 换 MQ:@TenantJob 之外,RocketMQ/Kafka 没有通用封装,业务需自行引 starter 并复用租户 hook。
  • 补可靠性:AbstractRedisStreamMessageListener 的 TODO 明说「消费失败重试/幂等/日志」未实现,重要消息请在业务层自己做去重表或改用 RocketMQ。

6. 常见坑 ​

  1. 消息类必须有无参构造:AbstractRedisChannelMessageListener 在构造器里 messageType.getDeclaredConstructor().newInstance().getChannel(),用 @Builder/全参构造覆盖默认构造会直接启动失败。
  2. Stream 消费失败不会自动重试,会「卡」在 pending:cancelOnError(t -> false) 保证不取消订阅,但消息要等 RedisPendingMessageResendJob 在 5 分钟后重投;这期间消息既未 ACK 也不会被别人抢到。
  3. 两个补偿 Job 的锁 key 是共享的:注释警告 IoT 侧与主应用若共用一把锁,会导致其中一侧的 Stream 无限积压(各自有独立的 …:lock:iot 变体)。
  4. Redis 版本硬门槛 5.0:checkRedisVersion 不通过直接抛异常,本地用旧版 Redis 起不来,不是配置问题。
  5. RedisMQTemplate 的拦截器顺序:sendMessageBefore 正序、sendMessageAfter 倒序,拦截器之间有依赖时(如先加租户头再加签名头)要靠 @Order 控顺序。
  6. RabbitMQ 只有 MessageConverter:没有队列声明、没有监听器容器配置,业务侧仍需自己写 @RabbitListener 与 Queue/Exchange Bean。

7. 关联页面 ​