JoyD/Web/Vue/CubeLib/docs/CubeWebSocket.md

# CubeWebSocket

一个功能完善的 WebSocket 组件，支持自动连接、重连、消息队列、心跳机制等功能。

## 基础用法

```vue
<template>
  <div>
    <div>状态: {{ status }}</div>
    <div>消息数量: {{ messages.length }}</div>
    <CubeWebSocket
      ws-url="ws://localhost:8086/ws"
      :auto-connect="true"
      :reconnect="true"
      :debug-mode="true"
      @connected="handleConnected"
      @disconnected="handleDisconnected"
      @message="handleMessage"
      @status-changed="handleStatusChanged"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const status = ref('disconnected')
const messages = ref([])

const handleConnected = () => {
  console.log('WebSocket 已连接')
  status.value = 'connected'
}

const handleDisconnected = (code, reason) => {
  console.log('WebSocket 已断开:', code, reason)
  status.value = 'disconnected'
}

const handleMessage = (message) => {
  console.log('收到消息:', message)
  messages.value.push(message)
}

const handleStatusChanged = (newStatus) => {
  console.log('状态变化:', newStatus)
  status.value = newStatus
}
</script>
```

## Props

| 参数 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|---------|-------|
| wsUrl | WebSocket 服务器地址 | String | '' | 否 |
| autoConnect | 是否自动连接 | Boolean | true | 否 |
| reconnect | 是否自动重连 | Boolean | true | 否 |
| maxReconnectDelay | 最大重连延迟（毫秒） | Number | 30000 | 否 |
| debugMode | 是否开启调试模式 | Boolean | false | 否 |
| heartbeatInterval | 心跳间隔（毫秒） | Number | 30000 | 否 |
| connectTimeout | 连接超时（毫秒） | Number | 10000 | 否 |
| maxQueueSize | 消息队列最大长度 | Number | 100 | 否 |

### Props 说明

#### wsUrl
WebSocket 服务器的完整 URL 地址。如果为空字符串，则使用默认值 `ws://localhost:8086/ws`。

**验证规则**：如果提供值，必须是有效的 URL 格式。

#### autoConnect
组件挂载时是否自动连接到 WebSocket 服务器。

#### reconnect
连接断开后是否自动重连。重连使用指数退避策略，延迟从 1 秒开始，每次失败后翻倍，最大不超过 `maxReconnectDelay`。

#### maxReconnectDelay
重连的最大延迟时间（毫秒）。默认为 30 秒。

#### debugMode
是否开启调试模式。开启后会在控制台输出详细的日志信息，包括：
- 连接状态变化
- 消息发送和接收
- 错误信息
- 定时器状态

#### heartbeatInterval
心跳检测的间隔时间（毫秒）。连接成功后会定期发送 `ping` 消息以保持连接活跃。

#### connectTimeout
连接超时时间（毫秒）。如果在指定时间内连接未建立，将自动关闭连接并触发 `error` 事件。

#### maxQueueSize
消息队列的最大长度。当连接未建立时，发送的消息会被加入队列。如果队列已满，新消息将被丢弃并触发 `message-failed` 事件。

## Events

| 事件名 | 说明 | 参数 |
|--------|------|------|
| connected | 连接成功 | - |
| disconnected | 连接断开 | (code, reason) |
| error | 连接错误 | error |
| message | 收到消息 | message |
| status-changed | 状态变化 | status |
| connecting | 开始连接 | - |
| reconnecting | 开始重连 | - |
| message-sent | 消息已发送 | message |
| message-queued | 消息已加入队列 | message |
| message-failed | 消息发送失败 | { message, reason, error? } |

### Events 说明

#### connected
WebSocket 连接成功建立时触发。

#### disconnected
WebSocket 连接关闭时触发。参数包括：
- `code`: 关闭代码（数字）
- `reason`: 关闭原因（字符串）

#### error
发生错误时触发。参数为错误对象。

#### message
收到服务器消息时触发。参数为解析后的消息对象。

#### status-changed
连接状态变化时触发。参数为新的状态字符串，可能的值：
- `disconnected`: 未连接
- `connecting`: 连接中
- `connected`: 已连接
- `reconnecting`: 重连中
- `error`: 错误

#### connecting
开始建立连接时触发。

#### reconnecting
开始重连时触发。

#### message-sent
消息成功发送时触发。参数为发送的消息对象。

#### message-queued
消息加入队列时触发（连接未建立时）。参数为消息对象。

#### message-failed
消息发送失败时触发。参数为对象：
- `message`: 失败的消息对象
- `reason`: 失败原因（'queue_full' 或 'send_error'）
- `error`: 错误对象（仅在 reason 为 'send_error' 时存在）

## Methods

组件通过 `defineExpose` 暴露了以下方法：

| 方法名 | 说明 | 参数 | 返回值 |
|--------|------|------|--------|
| connect | 连接 WebSocket | - | void |
| disconnect | 断开连接 | - | void |
| send | 发送消息 | (type, data) | void |
| reconnect | 手动触发重连 | - | void |
| getStatus | 获取当前状态 | - | string |
| isConnected | 是否已连接 | - | boolean |
| getQueueSize | 获取队列长度 | - | number |

### Methods 说明

#### connect
手动连接到 WebSocket 服务器。如果已经连接或正在连接，则跳过。

#### disconnect
断开 WebSocket 连接并停止所有定时器（心跳、重连等）。

#### send
发送消息到服务器。参数：
- `type`: 消息类型（字符串）
- `data`: 消息数据（对象）

如果连接已建立，消息会立即发送；否则加入队列。

#### reconnect
手动触发重连。通常不需要调用，组件会自动处理重连。

#### getStatus
返回当前连接状态字符串。

#### isConnected
返回布尔值，表示是否已连接。

#### getQueueSize
返回当前消息队列的长度。

## 消息协议

组件使用二进制协议发送和接收消息：

### 发送格式

```
字节 0: 消息类型（0=字符串，1=二进制）
字节 1-2: 扩展参数（2字节，小端序）
字节 3-6: 内容长度（4字节，小端序）
字节 7-N: 内容数据
```

发送的消息会被自动包装为以下格式：
```javascript
{
  version: 1,  // 协议版本
  type: '...', // 消息类型
  data: {...}  // 消息数据
}
```

### 接收格式

组件会自动解析接收到的二进制消息，并触发 `message` 事件。解析后的消息格式与发送格式相同。

## 使用场景

### 场景 1：简单的实时通信

```vue
<script setup>
import CubeWebSocket from 'joyd.web.vue.cubelib'

const wsRef = ref(null)

const sendMessage = () => {
  wsRef.value?.send('chat', { text: 'Hello' })
}
</script>

<template>
  <CubeWebSocket
    ref="wsRef"
    ws-url="ws://localhost:8086/ws"
    @message="(msg) => console.log(msg)"
  />
  <button @click="sendMessage">发送消息</button>
</template>
```

### 场景 2：自动重连和错误处理

```vue
<script setup>
import { ref } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const status = ref('disconnected')
const errorMessage = ref('')

const handleError = (error) => {
  errorMessage.value = error.message || '连接错误'
}
</script>

<template>
  <div>
    <div>状态: {{ status }}</div>
    <div v-if="errorMessage" class="error">{{ errorMessage }}</div>
    <CubeWebSocket
      ws-url="ws://localhost:8086/ws"
      :reconnect="true"
      @status-changed="status = $event"
      @error="handleError"
    />
  </div>
</template>
```

### 场景 3：消息队列监控

```vue
<script setup>
import { ref, watch } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const wsRef = ref(null)
const queueSize = ref(0)

watch(queueSize, (newSize) => {
  if (newSize > 50) {
    console.warn('消息队列积压:', newSize)
  }
})
</script>

<template>
  <div>
    <div>队列大小: {{ queueSize }}</div>
    <CubeWebSocket
      ref="wsRef"
      ws-url="ws://localhost:8086/ws"
      @message-queued="queueSize++"
      @message-sent="queueSize--"
    />
  </div>
</template>
```

## 注意事项

1. **URL 格式**：确保 `wsUrl` 是有效的 WebSocket URL 格式（`ws://` 或 `wss://` 开头）
2. **调试模式**：生产环境建议关闭 `debugMode` 以避免日志泄露
3. **消息队列**：队列大小受 `maxQueueSize` 限制，超出部分会被丢弃
4. **心跳机制**：心跳会定期发送 `ping` 消息，确保服务器端不会因超时断开连接
5. **重连策略**：使用指数退避，避免频繁重连造成服务器压力
6. **组件清理**：组件卸载时会自动断开连接并清理所有定时器

## 兼容性

- Chrome >= 16
- Firefox >= 11
- Safari >= 7
- Edge >= 12
- IE >= 10

## 许可证

MIT