xdz-hm/capability-socketio/Socket.IO连接配置说明.md

Socket.IO 连接配置说明

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

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

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

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

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

// 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（传输方式数组）

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

作用：

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

传输方式：

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

🔄 自动降级连接机制

机制说明

自动降级连接机制实际上是两个传输方式：

1. WebSocket（首选）
2. HTTP 长轮询（降级方案）

配置方式

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

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

流程：

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

优势：

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

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

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

流程：

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

优势：

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

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

opts.transports = ["websocket"];

问题：

• ❌ 如果 WebSocket 不可用，连接会失败
• ❌ 兼容性差

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

opts.transports = ["polling"];

问题：

• ❌ 性能较差（HTTP 头开销）
• ❌ 延迟较高

🎯 一般需要哪些配置？

标准配置（推荐）

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"
  }
};

最小配置（必需）

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

📊 Android 端 vs 鸿蒙端对比

Android 端（socket.io-client:2.1.2）

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
}

鸿蒙端（当前实现）

// 当前实现：手动实现自动降级
// 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（可选，用于传递认证信息）

推荐配置

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