Skip to content

消息与实时推送 ​

一句话:站内消息走 Redis(pub/sub 用于广播、stream 用于可靠消费),WebSocket 的跨实例推送复用同一套 MQ;「发消息」与「收消息」都被抽象成基类,业务只写消息体和 onMessage。

适用场景:新增一类站内通知、推送实时消息给指定用户/全体、排查「消息发了没收到」或「多实例只有一台收到」。

不适用场景:强一致的事务消息(这里没有事务消息,只有「先落库再发」的实践);外部系统对接的 MQ 用法(直接用 RabbitMQ/RocketMQ/Kafka 原生 API)。

1. 两种 Redis 消息模型 ​

模型语义抽象类发送消费
pub/sub广播、不持久、发完即忘AbstractRedisChannelMessageRedisMQTemplate#send(AbstractRedisChannelMessage)(#L38-L46)AbstractRedisChannelMessageListener
stream持久、有消费组、可重投AbstractRedisStreamMessageRedisMQTemplate#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装配方式现状
RabbitMQPmforgeRabbitMQAutoConfiguration,@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)
KafkaTenantKafkaEnvironmentPostProcessor 往 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-typeSender实现行
localLocalWebSocketMessageSender本机会话表直接发,单机可用#L87-L96
redisRedisWebSocketMessageSenderredisMQTemplate.send#L98-L114
rocketmqRocketMQWebSocketMessageSenderrocketMQTemplate.syncSend#L116-L133
rabbitmqRabbitMQWebSocketMessageSenderrabbitTemplate.convertAndSend#L135-L162
kafkaKafkaWebSocketMessageSenderkafkaTemplate.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(推荐,最简单)

  1. 消息体:public class DemoMessage extends AbstractRedisChannelMessage { private Long userId; };
  2. 监听器:@Component public class DemoMessageListener extends AbstractRedisChannelMessageListener<DemoMessage> { @Override public void onMessage(DemoMessage message) { ... } };
  3. 发送: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. 排错清单 ​

症状先看判断依据
发了消息没人消费监听器是否 @Componentpub/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消费线程租户为空 → 不做租户过滤
消费时抛「无租户」NPETenantContextHolder#getRequiredTenantIdRabbitMQ/Kafka 消费端没有租户透传,需手动 TenantUtils.execute
Redis 5.0 以下启动失败checkRedisVersionstream 需要 5.0+
消息体反序列化成空对象消息类必须有默认构造器与 getter/setter用的是 Jackson,不是 Java 序列化