主题
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 并返回 RecordId | mq/redis/core/RedisMQTemplate.java |
RedisMessageInterceptor | 4 个默认方法:sendMessageBefore/After、consumeMessageBefore/After | mq/redis/core/interceptor/RedisMessageInterceptor.java |
AbstractRedisMessage | 消息基类:headers(Map<String,String>)+ getHeader/addHeader | mq/redis/core/message/AbstractRedisMessage.java |
AbstractRedisChannelMessage / …Listener<T> | Pub/Sub:channel 名默认取类简名;监听器无参构造里反射拿泛型与 channel | mq/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),并注册两个补偿 Job | mq/redis/config/ |
RedisPendingMessageResendJob | 每分钟(cron = "35 * * * * ?")把 pending ≥ 5 分钟的消息重投 | mq/redis/core/job/ |
RedisStreamMessageCleanupJob | 每小时(cron = "0 0 * * * ?")XTRIM 保留最近 10000 条 | mq/redis/core/job/ |
PmforgeRabbitMQAutoConfiguration | @ConditionalOnClass(RabbitTemplate),注册 Jackson2JsonMessageConverter | mq/rabbitmq/config/ |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
PmforgeRedisMQProducerAutoConfiguration | @AutoConfiguration(after = PmforgeRedisAutoConfiguration.class) | RedisMQTemplate(StringRedisTemplate, List<RedisMessageInterceptor>),构造时逐个 addInterceptor |
PmforgeRedisMQConsumerAutoConfiguration | @EnableScheduling + after = PmforgeRedisAutoConfiguration.class | RedisMessageListenerContainer(@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. 常见坑
- 消息类必须有无参构造:
AbstractRedisChannelMessageListener在构造器里messageType.getDeclaredConstructor().newInstance().getChannel(),用@Builder/全参构造覆盖默认构造会直接启动失败。 - Stream 消费失败不会自动重试,会「卡」在 pending:
cancelOnError(t -> false)保证不取消订阅,但消息要等RedisPendingMessageResendJob在 5 分钟后重投;这期间消息既未 ACK 也不会被别人抢到。 - 两个补偿 Job 的锁 key 是共享的:注释警告 IoT 侧与主应用若共用一把锁,会导致其中一侧的 Stream 无限积压(各自有独立的
…:lock:iot变体)。 - Redis 版本硬门槛 5.0:
checkRedisVersion不通过直接抛异常,本地用旧版 Redis 起不来,不是配置问题。 RedisMQTemplate的拦截器顺序:sendMessageBefore正序、sendMessageAfter倒序,拦截器之间有依赖时(如先加租户头再加签名头)要靠@Order控顺序。- RabbitMQ 只有 MessageConverter:没有队列声明、没有监听器容器配置,业务侧仍需自己写
@RabbitListener与Queue/ExchangeBean。
7. 关联页面
- starter-redis:
RedisTemplate与Spring Data Redis版本 - starter-websocket:
sender-type=redis复用本模块 - starter-biz-tenant:租户头的发送与恢复
- 横切机制、定时任务