143 lines
3.1 KiB
Markdown
143 lines
3.1 KiB
Markdown
# 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);
|
||
}
|
||
```
|
||
|
||
|