# websocket-java-demo

**Repository Path**: xingk/websocket-java-demo

## Basic Information

- **Project Name**: websocket-java-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket Java Demo

本项目演示了基于 **Spring Boot + WebSocket (STOMP)** 的即时通讯方案，遵循模块化与高内聚设计原则。实现了广播消息、点对点个人消息、异常处理、心跳检测及断线重连等企业级功能。

## ✨ 核心功能

### 1. 通讯模式
- **广播消息**：向 `/topic/public` 发送消息，所有在线客户端可见。
- **点对点消息**：向指定用户（UserId）推送私信，通过 `/user/queue/messages` 接收，保障隐私。
- **用户身份绑定**：通过 URL 参数（`/ws?userId=xxx`）在握手阶段自动绑定 Principal，无需复杂认证。

### 2. 健壮性设计
- **心跳检测**：双向心跳（Incoming/Outgoing 均为 10s），及时剔除死链。
- **断线重连**：前端实现指数退避算法（2s, 4s, 8s... Max 30s）自动重连，网络波动无感知。
- **连接保护**：包含连接超时（10s）与资源就绪检查，防止页面卡死。
- **备用 CDN**：SockJS/STOMP.js 库加载支持自动降级（jsDelivr -> unpkg），提升可用性。

### 3. 规范与体验
- **接口先行**：定义标准 DTO（`BroadcastMessageRequest` / `PersonalMessageRequest`）与统一响应结构 `MessageResponse`。
- **异常处理**：
  - **参数校验**：使用 Jakarta Validation (@Valid) 拦截非法入参。
  - **全局异常**：`@MessageExceptionHandler` 捕获业务异常，并通过 `/user/queue/errors` 精准反馈给触发者。
- **前端体验**：
  - 实时日志面板：清晰展示发送/接收/错误/连接状态日志。
  - 状态指示灯：直观显示 未连接(灰) / 连接中(黄) / 已连接(绿) / 重连倒计时。
  - 性能优化：Gzip 压缩、DNS 预解析、资源缓存控制。

---

## 🏗 模块结构

```
src/main/java/com/example/websocket/
├── api/                  # 接口定义层
│   ├── dto/              # 数据传输对象 (Request/Response)
│   └── ErrorCode.java    # 统一错误码枚举
├── config/               # 配置层
│   ├── WebSocketConfig.java       # STOMP代理与端点配置
│   └── UserHandshakeHandler.java  # 握手拦截与用户绑定
├── controller/           # 适配层
│   ├── MessageController.java     # STOMP 消息路由
│   └── FaviconController.java     # 静态资源适配
├── service/              # 业务逻辑层
│   └── MessagingService.java      # 消息推送服务接口
└── exception/            # 异常处理层
    ├── BusinessException.java     # 业务异常定义
    └── GlobalExceptionHandler.java # 全局异常处理器
```

## 🚀 快速开始

### 1. 启动服务
确保已安装 JDK 17+ 和 Maven。
```bash
mvn spring-boot:run
```
服务默认运行在 `http://localhost:8080`。

### 2. 前端验证
打开浏览器访问：[http://localhost:8080/index.html](http://localhost:8080/index.html)

#### 场景一：广播测试
1. 输入 UserId `u1`，点击 **连接**。
2. 在 **广播发送** 区域输入内容，点击发送。
3. 日志区将显示 `[发送-广播]` 和 `[接收-广播]`（自己也能收到）。

#### 场景二：个人消息测试
1. 打开第二个浏览器窗口，输入 UserId `u2`，点击 **连接**。
2. 回到 `u1` 窗口，在 **个人消息发送** 区域：
   - 目标用户ID：`u2`
   - 点击发送。
3. `u1` 窗口显示 `[发送-个人] to=u2`。
4. `u2` 窗口显示 `[接收-个人] from=u1`。

#### 场景三：异常与重连测试
- **参数校验**：清空消息内容发送，将收到 `[错误]` 回调提示参数不能为空。
- **断线重连**：停止后端服务，前端日志提示 `[底层连接关闭]` 并开始倒计时重连；重启后端后自动恢复连接。

## 🔧 扩展指南

- **外部消息代理**：目前使用内存级 `SimpleBroker`。如需集群部署，请在 `WebSocketConfig` 中开启 `enableStompBrokerRelay` 对接 RabbitMQ/ActiveMQ。
- **安全认证**：当前仅演示 ID 绑定。生产环境建议集成 Spring Security，在握手阶段验证 Token。
- **消息持久化**：需结合数据库与外部 MQ 实现离线消息存储与推送。