ContiNew

切换日光/暗黑模式

WebSocket ​

最后更新: 4 天前
实践版本: v2.16.0
提示文档具有版本时效性，部分内容可能已不适用于当前版本。如发现过时内容，请联系作者进行更新。

简介 ​

continew-starter-messaging-websocket 是 ContiNew Starter 消息模块提供的 WebSocket 服务端封装（@since 2.1.0），自动注册 WebSocket 端点并管理客户端会话，支持定向推送与全体广播，鉴权接入点可插拔。

主要特性 ​

  • 开箱即用： 自动注册 WebSocket 端点（默认 /websocket）及会话生命周期管理
  • 灵活推送： 支持按客户端定向、批量（@since 2.12.1）及全量广播（@since 2.12.1）发送消息
  • 会话管理可插拔： 默认提供内存会话 DAO，支持自定义实现（如分布式存储）
  • 鉴权可插拔： 通过实现 WebSocketClientService 接口接入自定义认证逻辑

快速开始 ​

引入依赖 ​

pom.xml
xml
<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-messaging-websocket</artifactId>
</dependency>

添加配置 ​

配置详情请查看：top.continew.starter.messaging.websocket.autoconfigure.WebSocketProperties（@since 2.1.0）。

application.yml
yaml
--- ### WebSocket 配置
continew-starter.messaging:
  websocket:
    # 是否启用（默认 true）
    enabled: true
    # 路径（默认 /websocket）
    path: /websocket
    # 允许跨域的域名（默认 *）
    allowed-origins:
      - '*'
    # 客户端 ID Key（握手时存入会话 attributes 的键名，默认 CLIENT_ID）
    client-id-key: CLIENT_ID

实现客户端身份接入 ​

必须提供 WebSocketClientService 实现并注册为 Bean，在握手阶段返回客户端 ID（例如当前登录用户 ID），客户端 ID 的语义决定了"定向推送"的粒度：

java
@Component
public class WebSocketClientServiceImpl implements WebSocketClientService {

    @Override
    public String getClientId(ServletServerHttpRequest request) {
        // 可从握手请求参数/Header/会话中解析凭证，认证失败可抛出异常阻断握手
        // 示例：解析 token 并校验，返回用户唯一标识
        return ...;
    }
}

必须实现 WebSocketClientService

WebSocketAutoConfiguration 中 WebSocketClientService 的默认实现会直接抛出异常，即必须由业务方提供自己的实现 Bean，否则启动报错。

发送消息 ​

使用 WebSocketUtils 工具类推送消息：

java
// 发送给指定客户端（@since 2.1.0）
WebSocketUtils.sendMessage("10001", "hello");

// 批量发送（@since 2.12.1）
WebSocketUtils.sendMessage(List.of("10001", "10002"), "hello");

// 广播给所有在线客户端（@since 2.12.1）
WebSocketUtils.sendMessage("hello");

客户端 ID 与会话的对应关系由 WebSocketSessionDao 管理，默认为内存实现（DefaultWebSocketSessionDao，同一客户端仅保留一个会话）；集群部署时实现该接口自行存储（listAll()、listAllSessionIds() 方法 @since 2.12.1）。

变更历史 ​

  • v2.1.0：新增模块；v2.1.1：优化相关配置及命名
  • v2.12.1：新增发送消息给所有客户端、批量发送消息方法
  • v2.16.0：优化部分类命名

核心依赖 ​

依赖描述
org.springframework.boot:spring-boot-starter-websocketSpring WebSocket 服务端支持
top.continew.starter:continew-starter-core核心模块