# Socket.IO 连接配置说明

## 📋 Socket.IO 连接配置的三个部分

### 1. 主连接地址（服务器地址）

```typescript
// 服务器的基础 URL
const serverUrl = "http://example.com:3000";
```

**作用**：指定 Socket.IO 服务器的地址

### 2. path（Socket.IO 服务路径）

```typescript
// Socket.IO 服务的路径（默认是 "/socket.io/"）
opts.path = "/socket.io/";
```

**作用**：
- 指定 Socket.IO 服务在服务器上的路径
- 默认值是 `/socket.io/`
- 如果服务器将 Socket.IO 部署在其他路径，需要修改此配置

**URL 构建**：
```
http://example.com:3000/socket.io/?EIO=4&transport=websocket
         ↑                    ↑
    服务器地址             服务路径
```

### 3. transports（传输方式数组）

```typescript
// 传输方式数组，Socket.IO 会按顺序尝试
opts.transports = ["websocket", "polling"];
```

**作用**：
- 指定客户端可以使用的传输方式
- Socket.IO 会**按数组顺序**尝试连接
- 如果第一个失败，自动尝试下一个

**传输方式**：
- `"websocket"` - WebSocket 传输（实时双向通信）
- `"polling"` - HTTP 长轮询（降级方案）

## 🔄 自动降级连接机制

### 机制说明

**自动降级连接机制实际上是两个传输方式**：
1. **WebSocket**（首选）
2. **HTTP 长轮询**（降级方案）

### 配置方式

#### 方式1：先 WebSocket，失败则降级到 HTTP 长轮询（推荐）

```typescript
opts.transports = ["websocket", "polling"];
```

**流程**：
```
1. 尝试 WebSocket 连接
   ↓ 失败
2. 自动降级到 HTTP 长轮询
   ↓
3. 连接成功
```

**优势**：
- ✅ 优先使用性能更好的 WebSocket
- ✅ WebSocket 失败时自动降级，确保连接成功

#### 方式2：先 HTTP 长轮询，然后升级到 WebSocket（默认）

```typescript
opts.transports = ["polling", "websocket"];
// 或者不设置，使用默认值
```

**流程**：
```
1. 先使用 HTTP 长轮询连接
   ↓ 成功
2. 尝试升级到 WebSocket
   ↓
3. 使用 WebSocket（如果升级成功）
```

**优势**：
- ✅ 兼容性最好（HTTP 长轮询几乎都支持）
- ✅ 连接成功后可以升级到 WebSocket

#### 方式3：只使用 WebSocket（不推荐）

```typescript
opts.transports = ["websocket"];
```

**问题**：
- ❌ 如果 WebSocket 不可用，连接会失败
- ❌ 兼容性差

#### 方式4：只使用 HTTP 长轮询（不推荐）

```typescript
opts.transports = ["polling"];
```

**问题**：
- ❌ 性能较差（HTTP 头开销）
- ❌ 延迟较高

## 🎯 一般需要哪些配置？

### 标准配置（推荐）

```typescript
const options = {
  // 1. 服务器地址（必需）
  serverUrl: "http://example.com:3000",
  
  // 2. Socket.IO 服务路径（可选，默认 "/socket.io/"）
  path: "/socket.io/",
  
  // 3. 传输方式（可选，默认 ["polling", "websocket"]）
  transports: ["websocket", "polling"], // 推荐：先 WebSocket，失败则降级
  
  // 4. 查询参数（可选，用于传递 token 等）
  query: {
    token: "your_token"
  },
  
  // 5. HTTP 头（可选，用于传递认证信息）
  extraHeaders: {
    "Authorization": "Bearer your_token"
  }
};
```

### 最小配置（必需）

```typescript
const options = {
  serverUrl: "http://example.com:3000", // 必需
  // 其他使用默认值
};
```

## 📊 Android 端 vs 鸿蒙端对比

### Android 端（socket.io-client:2.1.2）

```kotlin
val options = IO.Options().apply {
    // ① 主连接地址（在 IO.socket() 中指定）
    // socket = IO.socket("http://example.com:3000", options)
    
    // ② path（默认 "/socket.io/"，可以不设置）
    // path = "/socket.io/" // 默认值
    
    // ③ transports（默认 ["polling", "websocket"]，可以不设置）
    // transports = arrayOf("polling", "websocket") // 默认值
    
    // ④ query（用于传递 token）
    query = "token=$token"
    
    // ⑤ extraHeaders（用于传递认证信息）
    extraHeaders = mapOf("Authorization" to listOf("Bearer $token"))
    
    // ⑥ 其他配置
    reconnection = false
}
```

### 鸿蒙端（当前实现）

```typescript
// 当前实现：手动实现自动降级
// 1. 先尝试 WebSocket
// 2. 失败则降级到 HTTP 长轮询

// 需要扩展：支持 transports 配置
```

## 🔧 需要扩展的功能

为了让鸿蒙端与 Android 端完全一致，需要支持：

1. ✅ **path 配置**（当前已支持，默认 "/socket.io/"）
2. ⚠️ **transports 配置**（当前是硬编码的顺序，需要改为可配置）
3. ✅ **query 配置**（当前已支持，通过 URL 参数传递）
4. ⚠️ **extraHeaders 配置**（HTTP 长轮询已支持，WebSocket 需要扩展）

## 📝 总结

### 自动降级连接机制

- **两个传输方式**：WebSocket 和 HTTP 长轮询
- **一个连接地址**：服务器地址
- **一个服务路径**：Socket.IO 服务路径（默认 "/socket.io/"）

### 一般需要的配置

1. **服务器地址**（必需）
2. **path**（可选，默认 "/socket.io/"）
3. **transports**（可选，推荐 `["websocket", "polling"]`）
4. **query**（可选，用于传递 token）
5. **extraHeaders**（可选，用于传递认证信息）

### 推荐配置

```typescript
{
  serverUrl: "http://example.com:3000",
  path: "/socket.io/",                    // 默认值，可以不设置
  transports: ["websocket", "polling"],   // 推荐：先 WebSocket，失败则降级
  query: { token: "xxx" },               // 可选
  extraHeaders: { "Authorization": "Bearer xxx" } // 可选
}
```