cn-rdms/rdms-framework/rdms-spring-boot-starter-websocket

rdms-spring-boot-starter-websocket

1. 模块定位

rdms-spring-boot-starter-websocket 是 WebSocket 基础设施模块，用于统一处理连接、会话管理、消息分发与消息发送，并支持多节点场景下的广播投递。

模块聚合的核心能力：

• WebSocket 自动装配与路径注册
• 登录用户绑定与会话管理
• JSON 消息协议与监听器分发
• 消息发送与多节点广播

2. 设计思路

• 统一 JSON 消息协议（type + content），通过 type 分发到对应监听器，降低业务耦合。
• 通过 WebSocketSessionManager 统一管理会话，支持按用户类型/用户编号/会话 ID 进行推送。
• 通过可插拔 sender-type 支持单机与多节点广播（local/redis/rocketmq/rabbitmq/kafka）。
• 与安全体系结合，在握手阶段写入 LoginUser，便于后续鉴权与定向发送。

3. 功能模块

3.1 自动装配

RdmsWebSocketAutoConfiguration 会完成：

• 注册 WebSocket 路径与处理器
• 注册握手拦截器（默认 LoginUserHandshakeInterceptor）
• 注册 WebSocketSessionManager
• 放行 WebSocket 路径的安全校验
• 注册消息发送器（按 sender-type）

3.2 JSON 消息协议

内置统一消息结构：

{
  "type": "notice",
  "content": "{...}"
}

处理流程：

• JsonWebSocketMessageHandler 解析 JSON
• 根据 type 选择对应 WebSocketMessageListener
• 将 content 反序列化为监听器泛型类型并交给业务处理

内置 ping/pong：收到 ping 会直接返回 pong。

3.3 会话管理

WebSocketSessionManager 支持：

• 按 sessionId 获取会话
• 按 userType 获取会话列表
• 按 userType + userId 获取会话列表

用于定向推送和广播推送。

3.4 消息发送

统一使用 WebSocketMessageSender 发送消息：

• 按用户推送
• 按用户类型广播
• 按会话 ID 推送

消息会被封装为统一的 JsonWebSocketMessage 后发送。

3.5 多节点广播

sender-type 支持以下类型：

• local：单机直连（默认）
• redis / rocketmq / rabbitmq / kafka：通过 MQ 广播到各实例，再由各实例推送到本机会话

3.6 登录用户绑定

握手阶段会读取当前登录用户并写入 WebSocket Session：

• 需要前端通过 ?token={token} 形式携带令牌
• LoginUserHandshakeInterceptor 会将 LoginUser 写入 Session
• WebSocketFrameworkUtils 可获取 userId/userType/tenantId

4. 开发人员上手

4.1 引入依赖

<dependency>
    <groupId>com.njcn</groupId>
    <artifactId>rdms-spring-boot-starter-websocket</artifactId>
</dependency>

4.2 基础配置

rdms:
  websocket:
    enable: true
    path: /ws
    sender-type: local

说明：

• path 默认 /ws
• sender-type 默认 local
• enable 默认 true

4.3 连接方式

前端连接示例：

ws://{host}:{port}/ws?token={token}

4.4 编写消息监听器

@Component
public class NoticeMessageListener implements WebSocketMessageListener<NoticeDTO> {

    @Override
    public void onMessage(WebSocketSession session, NoticeDTO message) {
        // 处理消息
    }

    @Override
    public String getType() {
        return "notice";
    }
}

4.5 服务端推送

@Resource
private WebSocketMessageSender webSocketMessageSender;

public void push(Long userId, NoticeDTO notice) {
    webSocketMessageSender.sendObject(UserTypeEnum.ADMIN.getValue(), userId, "notice", notice);
}

4.6 多节点广播配置示例

Redis：

rdms:
  websocket:
    sender-type: redis

RocketMQ：

rdms:
  websocket:
    sender-type: rocketmq
    sender-rocketmq:
      topic: ws-topic
      consumer-group: ws-group

Kafka：

rdms:
  websocket:
    sender-type: kafka
    sender-kafka:
      topic: ws-topic
      consumer-group: ws-group

RabbitMQ：

rdms:
  websocket:
    sender-type: rabbitmq
    sender-rabbitmq:
      exchange: ws-exchange
      queue: ws-queue

注意：

• 使用 MQ 模式时，请确保对应 MQ 客户端依赖与连接配置已就绪。