主题
消息与实时推送
一句话:站内消息走 Redis(pub/sub 用于广播、stream 用于可靠消费),WebSocket 的跨实例推送复用同一套 MQ;「发消息」与「收消息」都被抽象成基类,业务只写消息体和
onMessage。
适用场景:新增一类站内通知、推送实时消息给指定用户/全体、排查「消息发了没收到」或「多实例只有一台收到」。
不适用场景:强一致的事务消息(这里没有事务消息,只有「先落库再发」的实践);外部系统对接的 MQ 用法(直接用 RabbitMQ/RocketMQ/Kafka 原生 API)。
1. 两种 Redis 消息模型
| 模型 | 语义 | 抽象类 | 发送 | 消费 |
|---|---|---|---|---|
| pub/sub | 广播、不持久、发完即忘 | AbstractRedisChannelMessage | RedisMQTemplate#send(AbstractRedisChannelMessage)(#L38-L46) | AbstractRedisChannelMessageListener |
| stream | 持久、有消费组、可重投 | AbstractRedisStreamMessage | RedisMQTemplate#send(AbstractRedisStreamMessage)(#L54-L64) | AbstractRedisStreamMessageListener |
选择标准很简单:丢了能不能接受。能接受(如刷新缓存、发通知)用 pub/sub;不能接受(如积分扣减后的后续动作)用 stream。
两者的「名字」都默认取类名:
AbstractRedisChannelMessage#getChannel()返回getClass().getSimpleName()(#L19-L21,字段上有@JsonIgnore);AbstractRedisStreamMessage#getStreamKey()同理(#L19-L21)。
所以「消息类名」就是「队列名」,重命名类等于换队列,老消息会留在旧 stream 里。
1.1 监听器怎么被注册
PmforgeRedisMQConsumerAutoConfiguration:
- pub/sub:
@ConditionalOnBean(AbstractRedisChannelMessageListener.class)(#L47),对每个 listener 执行container.addMessageListener(listener, new ChannelTopic(listener.getChannel()))(#L57)。新增一个@Component的 listener 就会被自动挂上,不需要改配置。 - stream:
redisStreamMessageListenerContainer(#L93-L136)@Bean(initMethod = "start", destroyMethod = "stop"),batchSize(10)(#L103)、targetType(String)(#L104)、autoAcknowledge(false)(#L129,手动 ack)、cancelOnError(t -> false)(#L130,单条失败不拖垮整个容器)、ReadOffset.lastConsumed()(#L125)。 - 启动时
checkRedisVersion要求 Redis >= 5.0(#L98、#L151-L161),因为 stream 是 5.0 引入的。 - consumerName 用
IP@PID(#L111、#L144-L146),多实例天然区分。
1.2 失败重试与清理
stream 的「至少一次」靠两个定时任务兜底(配置类上 @EnableScheduling,#L39):
| 任务 | 触发 | 行为 | 行 |
|---|---|---|---|
RedisPendingMessageResendJob | @Scheduled(cron = "35 * * * * ?") | 扫 pending,最后投递超过 5 分钟的重新 add 并 ack 旧消息;Redis 分布式锁防并发 | #L46、#L69-L104 |
RedisStreamMessageCleanupJob | @Scheduled(cron = "0 0 * * * ?") | ops.trim(streamKey, 10000, false) 精确裁剪 | #L53、#L79 |
AbstractRedisStreamMessageListener#onMessage 的 ack 是显式调用(#L71),但重试逻辑本身没实现,源码里留着 TODO(#L72-L76):异常、日志、幂等、重试都要业务自己保证。这是最常见的坑——以为框架会重试,其实只会重投 pending。
pub/sub 没有重试也没有持久化:AbstractRedisChannelMessageListener#onMessage 是 final,只做 JSON 解析、拦截器调用与业务回调,不捕获业务异常(#L55-L64),因此 onMessage 必须自己 try-catch,不要假设上游会重发。
2. 拦截器:横切消息的唯一入口
RedisMessageInterceptor(#L12-L26)有四个 default 空方法:sendMessageBefore/After、consumeMessageBefore/After。RedisMQTemplate 在发送前后按正序调用 before、倒序调用 after(#L75-L85),消费侧也一样(#L87-L101)——这是标准的栈式拦截器语义:谁先包装,谁最后收尾。
现成的实现就是租户透传 TenantRedisMessageInterceptor:发送前把 tenant-id 写进消息头(#L21-L26),消费前 setTenantId、消费后 clear()(#L29-L40)。
3. RabbitMQ / RocketMQ / Kafka:可选装配
三个依赖在 pmforge-spring-boot-starter-mq/pom.xml 里都是 <optional>true</optional>(#L28-L39),装配靠 @ConditionalOnClass,不引入就不生效:
| MQ | 装配方式 | 现状 |
|---|---|---|
| RabbitMQ | PmforgeRabbitMQAutoConfiguration,@ConditionalOnClass(name = "org.springframework.amqp.rabbit.core.RabbitTemplate")(#L15-L18),注册 Jackson2JsonMessageConverter(#L23-L26) | 只在生产端挂了 TenantRabbitMQMessagePostProcessor(TenantRabbitMQInitializer#L16-L22) |
| RocketMQ | 用官方 starter,租户模块在检测到 RocketMQTemplate 时注册收发 hook(TenantRocketMQInitializer#L22-L28) | 生产、消费两端都透传租户(TenantRocketMQSendMessageHook#L24-L30、TenantRocketMQConsumeMessageHook#L30-L44) |
| Kafka | TenantKafkaEnvironmentPostProcessor 往 spring.kafka.producer.properties.interceptor.classes 追加拦截器(#L19、#L25-L31) | 只有生产者拦截器 |
已知缺口:RabbitMQ 与 Kafka 的消费端不会自动恢复租户上下文。消费者要么自己从 header 取 tenant-id 再 TenantUtils.execute(tenantId, ...),要么接受「消费线程里租户为空」——此时任何 TenantBaseDO 查询都会抛 NullPointerException(TenantContextHolder#getRequiredTenantId)。这是排错时的高频原因。
4. WebSocket:五种 sender,一个会话表
WebSocket 只负责「连接」,跨实例推送走 MQ。PmforgeWebSocketAutoConfiguration 按 pmforge.websocket.sender-type 精确匹配装配(havingValue):
| sender-type | Sender | 实现 | 行 |
|---|---|---|---|
local | LocalWebSocketMessageSender | 本机会话表直接发,单机可用 | #L87-L96 |
redis | RedisWebSocketMessageSender | redisMQTemplate.send | #L98-L114 |
rocketmq | RocketMQWebSocketMessageSender | rocketMQTemplate.syncSend | #L116-L133 |
rabbitmq | RabbitMQWebSocketMessageSender | rabbitTemplate.convertAndSend | #L135-L162 |
kafka | KafkaWebSocketMessageSender | kafkaTemplate.send(...).get() | #L164-L181 |
非 local 的每种都配一个「消费者 + 消息体」:本机收到 MQ 消息后再调 xxxWebSocketMessageSender.send(...) 真正写回会话(RedisWebSocketMessageConsumer#L17-L21)。这条回路是「A 实例推送给连在 B 实例上的用户」的唯一方式。
发送入口在 AbstractWebSocketMessageSender:三个 send 重载最终归一到 send(sessionId, userType, userId, messageType, messageContent)(#L53-L74),doSend 组装 JSON、校验会话、session.sendMessage(#L83-L104)。业务层建议直接用 sendObject(...),省掉手动序列化。
会话管理在 WebSocketSessionManagerImpl:
idSessions(#L29)+userSessions(#L37-L38,userType -> userId -> sessions);- 按用户类型群发时会按租户过滤(
#L92-L113):取TenantContextHolder.getTenantId()(#L98),非空才比较会话的租户(#L104-L108); - ⚠️ 上下文为空时不过滤(比如 RabbitMQ/Kafka 消费线程),广播会发给所有租户;
- 按
userType + userId单发时完全不按租户过滤(#L116-L123),依赖 userId 全局唯一。
入站消息由 JsonWebSocketMessageHandler 处理(#L45-L81):空消息忽略、ping 回 pong、按 type 找 WebSocketMessageListener、解析 content、用会话上的租户执行 TenantUtils.execute(#L76-L77),异常只记日志。
5. 如何新增一种消息类型
Redis pub/sub(推荐,最简单)
- 消息体:
public class DemoMessage extends AbstractRedisChannelMessage { private Long userId; }; - 监听器:
@Component public class DemoMessageListener extends AbstractRedisChannelMessageListener<DemoMessage> { @Override public void onMessage(DemoMessage message) { ... } }; - 发送:
redisMQTemplate.send(new DemoMessage(...))。
Redis stream(要可靠)
消息体继承 AbstractRedisStreamMessage,监听器继承 AbstractRedisStreamMessageListener<T>(泛型必须写,否则构造时抛 IllegalStateException),并在 onMessage 里成功后再 ack。
WebSocket 业务消息
实现 WebSocketMessageListener<T> 并返回唯一的 getType()(示例:DemoWebSocketMessageListener#L44-L46 返回 "demo-message-send"),发送时 sender.sendObject(ADMIN, userId, "demo-message-send", payload)(#L32-L33)。getType() 重复会覆盖注册(JsonWebSocketMessageHandler#L39-L42 用 Map 收集)。
6. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
| 发了消息没人消费 | 监听器是否 @Component | pub/sub 容器只收集 AbstractRedisChannelMessageListener Bean(#L47) |
| stream 有 pending 一直不消费 | autoAcknowledge(false) + 业务异常 | 没 ack 就留在 pending;5 分钟后重投,但 onMessage 的 TODO 重试没实现 |
| 多实例只有一台收到 | pub/sub 是广播但 Redis 容器每实例都建 | 检查是否误用了 stream 的同一个 group(同组内负载均衡) |
| WebSocket 推送只在单机生效 | pmforge.websocket.sender-type | 多实例必须换成 redis/rocketmq/rabbitmq/kafka,local 只发本机会话 |
| WebSocket 广播串租户 | WebSocketSessionManagerImpl#L98-L108 | 消费线程租户为空 → 不做租户过滤 |
| 消费时抛「无租户」NPE | TenantContextHolder#getRequiredTenantId | RabbitMQ/Kafka 消费端没有租户透传,需手动 TenantUtils.execute |
| Redis 5.0 以下启动失败 | checkRedisVersion | stream 需要 5.0+ |
| 消息体反序列化成空对象 | 消息类必须有默认构造器与 getter/setter | 用的是 Jackson,不是 Java 序列化 |