Flutter 与 OpenHarmony 下 web_socket 标准 WebSocket 客户端跨平台实现

前言

虽然 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 → dart:io WebSocket
Web → HTML5 WebSocket API
  ↓
你的业务代码 (web_socket 统一接口)

二、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]);
}