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

3.3 关闭连接

void close(WebSocket socket) async {
  await socket.close(1000, 'Normal Closure');
  print('连接已关闭');
}

四、完整实战示例：鸿蒙实时消息接收器

本示例演示了一个健壮的消息客户端，包含连接初始化、消息分类处理以及关闭资源释放生命周期。

import 'package:web_socket/web_socket.dart';

class OhosChatClient {
  WebSocket? _socket;
  bool _isConnected = false;

  /// 启动连接
  Future<void> init() async {
    try {
      _socket = await WebSocket.connect(
        Uri.parse('wss://api.ohos-chat.com/v1'),
        timeout: Duration(seconds: 10),
      );
      _isConnected = true;
      _listen();
    } catch (e) {
      print('❌ 连接失败：$e');
    }
  }

  void _listen() {
    _socket?.events.listen((event) {
      if (event is TextDataReceived) {
        _handleText(event.text);
      } else if (event is CloseReceived) {
        _isConnected = false;
        print('🔌 服务器断开连接');
      }
    });
  }

  void _handleText(String message) {
    // 业务逻辑处理...
  }

  /// 资源回收
  void dispose() {
    _socket?.close();
  }
}

五、总结

web_socket 是 Dart 官方为了抹平平台差异而推出的标准化库。 建议所有新开发的 Flutter 项目，如果不需要使用 Socket.io 或 STOMP 等上层协议，而是直接使用原始 WebSocket，首选使用 package:web_socket 而不是直接用 dart:io。

对于 OpenHarmony 开发，它保证了你的网络层代码是未来兼容的（Future-proof），无论未来鸿蒙底层的网络栈如何演进，标准接口层都将保持稳定。