# websocket-spring-boot-starter

**Repository Path**: tangshitai/websocket-spring-boot-starter

## Basic Information

- **Project Name**: websocket-spring-boot-starter
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket Spring Boot Starter

一个功能强大、易于集成的WebSocket Spring Boot Starter，提供完整的WebSocket连接管理、消息处理、缓存和过滤功能。

## 项目简介

本项目是一个基于Spring Boot的WebSocket自动配置模块，旨在简化WebSocket服务的开发和集成。它提供了以下核心功能：

- 自动配置WebSocket端点
- 连接生命周期管理
- 消息发送与接收处理
- 消息缓存与重发
- 多维度消息过滤
- 服务类型级别的功能隔离
- 丰富的管理接口

## 快速开始

### 1. 添加依赖

在Spring Boot项目的`pom.xml`文件中添加以下依赖：

```xml
<dependency>
    <groupId>net.f3322.layman</groupId>
    <artifactId>websocket-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 启用WebSocket

在Spring Boot启动类上添加`@EnableWS`注解：

```java
@SpringBootApplication
@EnableWS
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

### 3. 创建WebSocket处理器

实现自定义的消息处理器：

```java
@Component
public class MyWsHandler implements WsMsgHandler {
    @Override
    public String supportType() {
        return "myService";
    }
    
    @Override
    public void handle(WebSocketMessage message) {
        // 处理接收到的消息
        System.out.println("Received message: " + message.getContent());
    }
}
```

### 5. 发送消息

```java
@Autowired
private WsMsgSender wsMsgSender;

// 发送消息到指定连接
wsMsgSender.sendToConnection("connectionId", "Hello, WebSocket!");

// 发送消息到指定服务类型
wsMsgSender.sendToService("myService", "Hello to all myService clients!");

// 发送消息到指定服务+组
wsMsgSender.sendToGroup("myService", "myGroup", "Hello to myGroup!");
```

## 功能特性

### 1. 连接管理

- 自动维护WebSocket连接生命周期
- 支持连接超时设置
- 心跳检测机制
- 连接统计信息

### 2. 消息处理

- 基于服务类型的消息路由
- 支持多种消息发送方式（连接、服务、组）
- 异步消息处理
- 消息格式灵活可扩展

### 3. 消息缓存

- 支持服务级别缓存
- 支持组级别缓存
- 缓存开关可配置
- 缓存统计与管理

### 4. 过滤器机制

- 连接过滤器（WsConnectFilter）
- 消息接收前过滤器（WsReceivePreFilter）
- 消息发送前过滤器（WsSendMsgPreFilter）
- 支持服务类型级别的过滤器匹配

### 5. 异常处理

- 统一异常处理机制
- 可自定义异常响应格式
- 异常详情可配置

## 配置说明

在`application.yml`或`application.properties`中配置WebSocket相关参数：

### 基础配置

```yaml
websocket:
  # 连接超时时间（毫秒）
  connection-timeout: 180000
  # 心跳检测间隔（毫秒）
  heartbeat-interval: 30000
```

### 缓存配置

```yaml
websocket:
  cache:
    # 每个服务/组的最大缓存消息数
    max-cached-messages: 100

### 错误处理配置

```yaml
websocket:
  error-handler:
    # 默认错误码
    default-error-code: 500
    # 默认错误消息
    default-error-message: "发生意外错误"
    # 错误消息格式
    error-message-format: '{"code": ${code}, "message": "${message}"}'
    # 是否在错误响应中包含详细信息（异常类型、堆栈跟踪等）
    include-details: false
```

### 线程池配置

```yaml
websocket:
  executor:
    # 核心线程数
    core-pool-size: 10
    # 最大线程数
    max-pool-size: 20
    # 线程存活时间（秒）
    keep-alive-seconds: 60
    # 队列容量
    queue-capacity: 1000
    # 线程名称前缀
    thread-name-prefix: "websocket-msg-"
    # 是否允许核心线程超时
    allow-core-thread-timeout: false
```

### 安全配置

```yaml
websocket:
  security:
    # OAuth2Authentication中principal对象的账户字段名
    principal-account-field: "account"
```

## 使用指南

### 消息处理器开发

实现`WsMsgHandler`接口，处理特定类型的消息：

```java
@Component
public class UserHandler implements WsMsgHandler {
    @Override
    public String supportType() {
        return "userService"; // 指定支持的服务类型
    }
    
    @Override
    public void handle(WebSocketMessage message) {
        // 处理userService类型的消息
        String content = message.getContent();
        String userId = message.getUserId();
        
        // 处理业务逻辑
        // ...
    }
}
```

### 过滤器开发

#### 连接过滤器

```java
@Component
@Order(1)
public class AuthFilter implements WsConnectFilter {
    @Override
    public void filter(WsConnectContext context, WsConnectFilterChain chain) {
        // 验证连接参数
        String token = context.getParameter("token");
        if (token == null || !validateToken(token)) {
            context.reject("Invalid token");
            return;
        }
        
        // 设置连接属性
        context.setServiceType("userService");
        context.setGroupType("userGroup");
        context.setUserId("user123");
        
        // 继续执行过滤器链
        chain.doFilter(context);
    }
    
    // 仅对userService生效
    @Override
    public String supportService() {
        return "userService";
    }
}
```

#### 消息接收过滤器

```java
@Component
@Order(2)
public class LogFilter implements WsReceivePreFilter {
    @Override
    public void filter(WsReceivePreContext context, WsReceivePreFilterChain chain) {
        // 记录消息日志
        System.out.println("Received message from " + context.getUserId() + ": " + context.getMessage());
        
        // 继续执行过滤器链
        chain.doFilter(context);
    }
    
    // 对所有服务生效
    @Override
    public String supportService() {
        return null;
    }
}
```

### 消息发送

```java
@Autowired
private WsMsgSender wsMsgSender;

// 发送消息到指定连接
wsMsgSender.sendToConnection("connectionId", "Hello!");

// 发送消息到指定用户
wsMsgSender.sendToUser("userId", "Hello, user!");

// 发送消息到指定服务
wsMsgSender.sendToService("userService", "Hello to all users!");

// 发送消息到指定服务+组
wsMsgSender.sendToGroup("userService", "adminGroup", "Hello to admins!");
```

## 扩展开发

### 自定义连接管理器

实现`WsConnectionManager`接口，自定义连接管理逻辑：

```java
@Component
public class CustomConnectionManager implements WsConnectionManager {
    // 实现自定义连接管理逻辑
    // ...
}
```

### 自定义消息缓存

实现`WsMsgCacheManager`接口，自定义消息缓存策略：

```java
@Component
public class CustomCacheManager implements WsMsgCacheManager {
    // 实现自定义缓存逻辑
    // ...
}
```

### 自定义异常处理器

实现`WsExceptionHandler`接口，自定义异常处理逻辑：

```java
@Component
public class CustomExceptionHandler implements WsExceptionHandler {
    // 实现自定义异常处理逻辑
    // ...
}
```

## 管理接口

启用管理接口后，可以通过REST API管理WebSocket服务：

### 缓存配置接口

- `GET /api/cache/config` - 获取所有服务的缓存配置
- `GET /api/cache/config/{serviceType}` - 获取指定服务的缓存配置
- `PUT /api/cache/service/{serviceType}` - 更新服务级别缓存配置
- `PUT /api/cache/group/{serviceType}/{groupType}` - 更新组级别缓存配置
- `DELETE /api/cache/{serviceType}` - 清除指定服务的缓存

### 统计信息接口

- `GET /api/cache/stats` - 获取缓存统计信息
- `GET /api/connection/stats` - 获取连接统计信息
- `GET /api/threadpool/stats` - 获取线程池统计信息
- `GET /api/stats` - 获取综合统计信息

### 连接管理接口

- `GET /api/connection` - 获取所有连接列表
- `GET /api/connection/uid/{uid}` - 根据UID获取连接
- `GET /api/connection/user/{userId}` - 根据用户ID获取连接
- `GET /api/connection/group/{groupType}` - 根据组类型获取连接

## 高级特性

### 服务类型级别隔离

过滤器和处理器可以通过`supportService()`方法指定支持的服务类型，实现功能的服务级别隔离：

```java
// 仅对userService生效的过滤器
@Override
public String supportService() {
    return "userService";
}

// 对所有服务生效的过滤器
@Override
public String supportService() {
    return null;
}
```

### 消息缓存策略

缓存功能由后端服务实现类通过重写 `AbstractWebSocketEndpoint` 的抽象方法控制：

- **服务级别缓存**：通过重写 `enableServiceNameCache()` 方法启用，缓存所有发送给该服务的消息
- **组级别缓存**：通过重写 `enableGroupCache()` 方法启用，当组不为空时缓存该组的消息

缓存策略逻辑：
1. 如果服务缓存启用，则缓存所有发送消息（不管组缓存是否启用）
   - 组不为空时，同时缓存到服务级别和组级别
   - 组为空时，只缓存到服务级别
2. 如果服务缓存未启用但组缓存启用，则当组不为空时缓存该组的消息，组为空时不缓存
3. 如果服务缓存和组缓存都未启用，则不缓存任何消息

在连接建立时，会根据缓存配置自动重发缓存的消息：
- 服务缓存启用且组不为空：只重发组级别的消息
- 服务缓存启用且组为空：重发所有消息（包括服务级别和所有组级别）
- 组缓存启用且组不为空：重发该组的消息
- 组缓存启用且组为空：不重发任何消息

### 线程池管理

- 自定义线程池大小和存活时间
- 可配置队列容量
- 支持核心线程超时设置

## 常见问题

### 1. 如何解决WebSocket连接失败？

- 检查是否添加了`@EnableWS`注解
- 确保端口未被占用
- 检查连接URL是否正确
- 查看日志中的错误信息

### 2. 如何实现消息的可靠传递？

- 启用消息缓存功能
- 配置合适的缓存大小和超时时间
- 实现消息确认机制

### 3. 如何提高WebSocket的性能？

- 调整线程池参数
- 优化消息处理逻辑
- 合理使用缓存策略
- 减少不必要的过滤器

## 许可证

MIT License

## 联系我们

如有问题或建议，请联系：

- Email: layman@f3322.net
- GitHub: https://github.com/layman-f3322/websocket-spring-boot-starter