# WebSocket集成

## 规则（Rules）

# WebSocket协议联调规范

## 适用对象和范围

本规范适用于所有WebSocket协议联调对接的场景。

---

## 1. 消息结构规范

**规则**：WebSocket消息必须使用统一的消息信封格式（method + params）。

- ✅ 正确：`{"method": "chat_message", "params": {...}}`
- ❌ 错误：直接发送裸数据 `{"content": "你好"}`

**违反后果**：缺少消息方法导致接收方无法路由处理。  

---

## 2. 心跳机制规范

**规则**：禁止忽略心跳机制，心跳是保持长连接的关键。

**违反后果**：无心跳机制导致连接超时断开后无法自动恢复。

---

## 3. 重连机制规范

**规则**：必须实现自动重连机制，网络波动时自动恢复连接和订阅状态。

**违反后果**：无重连机制导致网络波动后连接永久断开。

## 方法（Methods）

# WebSocket协议联调方法

## 前置条件

- [ ] 已有WebSocket协议设计文档
- [ ] 服务端已实现WebSocket服务
- [ ] 客户端已实现WebSocket连接

---

## 流程概览

```
阅读协议文档 → 检查连接建立 → 检查消息收发 → 编写数据转换协议 → 逐消息类型验证 → 修复问题
```

---

## 详细步骤

### 步骤1：阅读WebSocket协议文档

分析协议文档，提取连接地址、消息方法、数据格式和通信流程。

### 步骤2：检查连接建立

检查服务端和客户端的WebSocket实现是否与协议文档一致。

### 步骤3：检查消息收发

## 技巧（Tips）

# WebSocket协议联调技巧

## 1. 使用统一消息信封

**适用场景**：需要多种消息类型时。

**具体做法**：定义统一的消息格式 `{method, params, msg_id, timestamp}`。

## 2. 心跳与重连策略

**适用场景**：需要保持长连接稳定时。

**具体做法**：客户端每30秒发送ping，服务端回复pong；断开后按指数退避策略重连。

## 3. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 连接失败 | URL错误或端口不通 | 检查连接地址和端口 |
| 消息收不到 | 消息类型不匹配 | 检查type值是否一致 |
| 连接频繁断开 | 心跳间隔不一致 | 统一心跳策略 |