WebSocket 实时通信

## 1. 功能简介
项目的 dtoc-spring-boot-starter-websocket 组件，基于 [Spring WebSocket](http://https://docs.spring.io/spring-framework/reference/web/websocket.html "Spring WebSocket")进行二次封装，实现了更加简单的使用方式。例如说，WebSocket 的认证、Session 的管理、WebSocket 集群的消息广播等等。

### 1.1 Token 身份认证
① 在 WebSocket 连接建立时，通过 QueryString 的 token 参数，进行认证。例如说：ws://127.0.0.1:48080/ws?token=xxx。
由于 WebSocket 是基于 HTTP 建立连接，所以它的认证可以复用项目的 TokenAuthenticationFilter 实现。
② 认证完成后，会通过 LoginUserHandshakeInterceptor 拦截器，将用户信息存储到 WebSocket Session 的 attributes 中。
这样，后续可以使用 WebSocketFrameworkUtils (opens new window)获取用户信息，例如说：

// WebSocketFrameworkUtils.java
// ① 获取当前用户
public static LoginUser getLoginUser(WebSocketSession session)

// ② 获得当前用户的类型
public static Integer getLoginUserType(WebSocketSession session)

// ③ 获得当前用户的编号
public static Integer getLoginUserType(WebSocketSession session)

// ④ 获得当前用户的租户编号
public static Long getTenantId(WebSocketSession session)

### 1.2 Session 会话管理
每个前端和后端建立的 WebSocket 连接，对应后端的一个 WebSocketSession 会话对象。由于后续需要对 WebSocketSession 进行消息的发送，所以需要进行管理。
① WebSocketSession 的管理，由 WebSocketSessionManager (opens new window)定义接口，由 WebSocketSessionManagerImpl (opens new window)具体实现。

// 添加和移除 Session
void addSession(WebSocketSession session);
void removeSession(WebSocketSession session);

// 获得 Session，多种维度
WebSocketSession getSession(String id); // Session 编号
Collection<WebSocketSession> getSessionList(Integer userType); // 用户类型
Collection<WebSocketSession> getSessionList(Integer userType, Long userId); // 用户编号
② WebSocket 建立和关闭连接时，通过 WebSocketSessionHandlerDecorator (opens new window)处理器，分别调用 WebSocketSessionManager 进行 Session 的添加和移除。

### 1.3 Message 消息格式
WebSocket 默认使用“文本”进行通信，而业务需要按照不同类型的消息，进行不同的处理。因此，项目定义了 JsonWebSocketMessage (opens new window)消息对象，包含 type 消息类型 + content 消息内容。
和 Spring MVC 对比，可以理解为：

![](/media/202408/2024-08-27_084912_160213.png)

具体 JsonWebSocketMessage 和 WebSocketMessageListener 详细说明，参见「1.4 Message 消息接收」小节。

### 1.4 Message 消息接收
① WebSocket 接收到项目后，会先交给 JsonWebSocketMessageHandler (opens new window)消息处理器，将消息解析成 JsonWebSocketMessage 对象。
之后，根据 type 消息类型，获得到 WebSocketMessageListener 实现类，并将 content 消息内容进一步解析成 Message 对象，交给它进行处理。

② 具体案例，可见 DemoWebSocketMessageListener (opens new window)、DemoSendMessage (opens new window)类。

### 1.5 Message 消息推送
① 项目的 WebSocketMessageSender (opens new window)接口，定义了给 Session 发送消息的方法。如下所示：

// WebSocketMessageSender.java

// ① 发送消息给指定用户
void send(Integer userType, Long userId, String messageType, String messageContent);
default void sendObject(Integer userType, Long userId, String messageType, Object messageContent) {
    send(userType, userId, messageType, JsonUtils.toJsonString(messageContent));
}

// ② 发送消息给指定用户类型
void send(Integer userType, String messageType, String messageContent);
default void sendObject(Integer userType, String messageType, Object messageContent) {
    send(userType, messageType, JsonUtils.toJsonString(messageContent));
}

// ③ 发送消息给指定 Session
void send(String sessionId, String messageType, String messageContent);
default void sendObject(String sessionId, String messageType, Object messageContent) {
    send(sessionId, messageType, JsonUtils.toJsonString(messageContent));
}

② WebSocketMessageSender 有多种实现类，如下：

![](/media/202408/2024-08-27_085019_998733.png)

默认配置下，使用 LocalWebSocketMessageSender 本地发送消息，不支持 WebSocket 集群。可通过修改 application.yaml 配置文件的 yudao.websocket.sender-type 来切换，如下：
<span style="font-family:楷体">

websocket:
    enable: true # websocket的开关
    path: /infra/ws # 路径
    sender-type: redis # 消息发送的类型，可选值为 local、redis、rocketmq、kafka、rabbitmq
    sender-rocketmq:
      topic: ${spring.application.name}-websocket # 消息发送的 RocketMQ Topic
      consumer-group: ${spring.application.name}-websocket-consumer # 消息发送的 RocketMQ Consumer Group
    sender-rabbitmq:
      exchange: ${spring.application.name}-websocket-exchange # 消息发送的 RabbitMQ Exchange
      queue: ${spring.application.name}-websocket-queue # 消息发送的 RabbitMQ Queue
    sender-kafka:
      topic: ${spring.application.name}-websocket # 消息发送的 Kafka Topic
      consumer-group: ${spring.application.name}-websocket-consumer # 消息发送的 Kafka Consumer Group</span>

## 2. 使用方案
目前有 2 种使用方案，分别是：

![](/media/202408/2024-08-27_085206_752862.png)

> 疑问：什么是上行？什么是下行？
上行：指的是“前端”发送消息给“后端”，WebSocket 和 HTTP 都可以。
下行：指的是“后端”发送消息给“前端”，只能使用 WebSocket。

### 2.1 方案一：纯 WebSocket

![](/media/202408/2024-08-27_085413_590593.png)

- 前端：见 [基础设施 -> WebSocket 测试] 菜单，对应 /views/infra/websocket/index.vue界面
- 后端：见 yudao-module-infra-biz 模块，对应 DemoWebSocketMessageListener 监听器
基于 WebSocket 实现的单聊和群聊，暂时不支持消息的持久化（刷新后，消息会消息）。建议，多多调试，更好的理解 WebSocket 流程。

### 2.1.1 后端代码
① 在 yudao-module-infra-biz 模块的 pom.xml 文件中，引入 yudao-spring-boot-starter-websocket 依赖。如下所示：
    <dependency>
        <groupId>cn.iocoder.cloud</groupId>
        <artifactId>yudao-spring-boot-starter-websocket</artifactId>
    </dependency>
修改该模块的 application.yaml 配置文件中，配置 yudao.websocket.enable 配置项，开启 WebSocket 功能。如下所示：

> websocket:
    enable: true # websocket的开关
    path: /infra/ws # 路径
    sender-type: local # 消息发送的类型，可选值为 local、redis、rocketmq、kafka、rabbitmq

② 新建 DemoWebSocketMessageListener 类，实现对应消息的处理。如下图所示：
DemoWebSocketMessageListener 类

③ 在 yudao-gateway 模块的 application.yaml 配置文件中，在 spring.cloud.gateway.routes 配置项中，添加 /infra/ws WebSocket 路径的路由。如下所示：

>  - id: infra-websocket # 路由的编号（WebSocket）
 uri: grayLb://infra-server
 predicates: # 断言，作为路由的匹配条件，对应 RouteDefinition 数组
- Path=/infra/ws/**

### 2.1.2 前端代码
① 建立 WebSocket 连接，如下图所示：

![](/media/202408/2024-08-27_085741_851012.png)

② 发送 WebSocket 消息，如下图所示：

![](/media/202408/2024-08-27_085753_969711.png)

③ 接收 WebSocket 消息。如下图所示：

![](/media/202408/2024-08-27_085807_077562.png)
### 2.2 方案二：WebSocket + HTTP

![](/media/202408/2024-08-27_085824_808967.png)
- 前端：见 [系统管理 -> 消息中心 -> 通知公告] 菜单，对应 /views/system/notice/index.vue (opens new window)界面的【推送】按钮
- 后端：见 yudao-module-system-biz 模块，对应 DemoWebSocketMessageListener (opens new window)监听器
点击某条公告的【推送】按钮，仅仅推送给所有在线用户。由于 WebSocket 目前暂时没全局建立，所以还是使用 [基础设施 -> WebSocket 测试] 菜单演示。如下图所示：

![](/media/202408/2024-08-27_085917_869840.png)
### 2.2.1 后端代码
【相同】① 在 yudao-module-infra-biz 模块的 pom.xml 文件中，引入 yudao-spring-boot-starter-websocket 依赖。

修改该模块的 application.yaml 配置文件中，配置 yudao.websocket.enable 配置项，开启 WebSocket 功能。如下所示：

> yudao:
  websocket:
    enable: true # websocket的开关
    path: /infra/ws # 路径
    sender-type: local # 消息发送的类型，可选值为 local、redis、rocketmq、kafka、rabbitmq
	
【不同】② 在 yudao-module-system-biz 模块的 pom.xml 文件中，引入 yudao-module-infra-api 依赖。如下所示：
>     <dependency>
        <groupId>cn.iocoder.cloud</groupId>
        <artifactId>yudao-module-infra-api</artifactId>
        <version>${revision}</version>
    </dependency>

修改该模块的 RpcConfiguration 类，增加对 WebSocketSenderApi 的引用。如下所示：
> // RpcConfiguration.java

@Configuration(proxyBeanMethods = false)
@EnableFeignClients(clients = {FileApi.class, WebSocketSenderApi.class})
public class RpcConfiguration {
}
不同】③ 在 yudao-module-system-biz 模块，在 NoticeController 类中，新建 #push(...) 方法，用于推送公告消息。如下图所示：

本质上，它替代了方案一的 DemoWebSocketMessageListener 类，走 HTTP 上行消息，替代 WebSocket 上行消息。

④ 在 dtpc-gateway 模块的 application.yaml 配置文件中，在 spring.cloud.gateway.routes 配置项中，添加 /infra/ws WebSocket 路径的路由。如下所示：
> <span style="font-family:楷体">        - id: infra-websocket # 路由的编号（WebSocket）
          uri: grayLb://infra-server
          predicates: # 断言，作为路由的匹配条件，对应 RouteDefinition 数组
            - Path=/infra/ws/**
</span>

### 2.2.2 前端代码
【相同】① 建立 WebSocket 连接，和方案一相同，不重复截图。

【不同】② 发送 HTTP 消息，如下图所示：

![](/media/202408/2024-08-27_090130_593560.png)
本质上，它替代了方案一的 WebSocket 上行消息，走 HTTP 上行消息。
【相同】③ 接收 WebSocket 消息，和方案一相同，不重复截图。