# rdms-spring-boot-starter-websocket

## 1. 模块定位

`rdms-spring-boot-starter-websocket` 是 WebSocket 基础设施模块，用于统一处理连接、会话管理、消息分发与消息发送。

模块聚合的核心能力：

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

## 2. 设计思路

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

## 3. 功能模块

### 3.1 自动装配

`RdmsWebSocketAutoConfiguration` 会完成：

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

### 3.2 JSON 消息协议

内置统一消息结构：

```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 登录用户绑定

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

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

## 4. 开发人员上手

### 4.1 引入依赖

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

### 4.2 基础配置

```yaml
rdms:
  websocket:
    enable: true
    path: /ws
```

说明：

- `path` 默认 `/ws`
- `enable` 默认 `true`

### 4.3 连接方式

前端连接示例：

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

### 4.4 编写消息监听器

```java
@Component
public class NoticeMessageListener implements WebSocketMessageListener<NoticeDTO> {

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

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

### 4.5 服务端推送

```java
@Resource
private WebSocketMessageSender webSocketMessageSender;

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