前言
虽然 dart:io 提供了 WebSocket 类，dart:html 也提供了 WebSocket 类，但这种'分裂'的 API 设计让编写跨平台（同时支持 Mobile/Web/Desktop）的代码变得异常痛苦。你需要使用条件导入 (if (dart.library.io) ...) 来分别处理。
web_socket 库就是为了解决这个问题而诞生的。它提供了一个统一的、平台无关的WebSocket 接口。
无论你的代码运行在 Android、iOS、Web 还是 OpenHarmony 上，它都会自动选择最底层的实现（在鸿蒙上通常是 dart:io），而从上层看代码完全一致。
对于 OpenHarmony 开发者，这意味着你可以直接复用现有 Flutter 项目中的 WebSocket 逻辑，无需为鸿蒙单独写条件编译分支。
一、核心原理
web_socket 本质上是一个 Facade（外观模式）。
- 你的业务代码调用统一接口
- 库内部自动检测当前运行环境（Native/OpenHarmony 或 Web）
- 根据环境分发到底层实现（
dart:io WebSocket或 HTML5 WebSocket API）
二、OpenHarmony 适配说明
在 OpenHarmony 上，Dart 运行时完全支持 dart:io。
因此，web_socket 库会透明地回退到基于 dart:io 的实现。
权限配置：
同样，别忘了在 module.json5 中申请 ohos.permission.INTERNET。
HTTPS/WSS 证书问题：
鸿蒙系统对 SSL 证书校验较为严格。如果连接开发环境的自签名 WSS 服务，可能会抛出 HandshakeException。在开发阶段，你可能需要重写 SecurityContext 来信任所有证书（仅限 Debug 模式）。
三、基础用例
3.1 建立连接
import 'package:web_socket/web_socket.dart';
void connect() async {
final uri = Uri.parse('wss://echo.websocket.org');
// 💡 统一接口：会自动根据 Platform 选择最底层的端侧实现
final socket = await WebSocket.connect(uri);
print('✅ 握手成功');
// 💡 监听消息：基于 Stream 的响应式处理
socket.events.listen((event) {
if (event is TextDataReceived) {
print('收到文本：${event.text}');
} else if (event is BinaryDataReceived) {
print('收到二进制：${event.data.length} 字节');
}
});
}
3.2 发送数据
void sendData(WebSocket socket) {
// 发送文本
socket.sendText('Hello OpenHarmony!');
// 发送二进制
socket.sendBytes([0x01, 0x02, 0x03]);
}
3.3 关闭连接
void close(WebSocket socket) async {
await socket.close(1000, 'Normal Closure');
print('连接已关闭');
}
四、完整实战示例：鸿蒙实时消息接收器
本示例演示了一个健壮的消息客户端，包含连接初始化、消息分类处理以及关闭资源释放生命周期。
