OpenHarmony 使用 shelf_web_socket 构建 WebSocket 服务端实战指南

3.3 示例三：处理二进制数据

WebSocket 不仅能传字符串，还能传字节流（如图片片段）。

import 'dart:typed_data';

var binaryHandler = webSocketHandler((WebSocketChannel webSocket) {
  webSocket.stream.listen((message) {
    if (message is List<int>) {
      print('收到二进制数据，长度：${message.length}');
      // 处理二进制逻辑...
    } else {
      print('收到文本：$message');
    }
  });
});

四、OpenHarmony 平台适配

4.1 网络权限

作为服务端，你需要监听端口，这同样需要 Internet 权限。

"requestPermissions": [
  {"name": "ohos.permission.INTERNET"}
]

4.2 后台运行限制

移动操作系统通常限制应用在后台运行服务。如果你的 WebSocket 服务需要长期运行，建议在前台 Service 中启动，或仅在 App 前台可见时运行。

五、完整实战示例：局域网即时画板服务端

本示例将在 OpenHarmony 设备上启动一个 WebSocket 服务。任何连接到该服务的客户端（可以是另一个 App 或浏览器）发送的坐标点，都会被广播给其他人，实现多端协同绘图。

5.1 示例代码

import 'dart:async';
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:shelf/shelf_io.dart' as shelf_io;
import 'package:shelf_web_socket/shelf_web_socket.dart';
import 'package:web_socket_channel/web_socket_channel.dart';

void main() {
  runApp(const MaterialApp(home: ServerPage()));
}

class ServerPage extends StatefulWidget {
  const ServerPage({super.key});

  @override
  State<ServerPage> createState() => _ServerPageState();
}

class _ServerPageState extends State<ServerPage> {
  HttpServer? _server;
  final List<WebSocketChannel> _sockets = [];
  final List<String> _logs = [];
  String _ipInfo = '获取中...';

  @override
  void initState() {
    super.initState();
    _getIpAddress();
  }

  Future<void> _getIpAddress() async {
    try {
      final interfaces = await NetworkInterface.list(type: InternetAddressType.IPv4);
      final ip = interfaces.first.addresses.first.address;
      setState(() => _ipInfo = ip);
    } catch (e) {
      setState(() => _ipInfo = '无法获取 IP');
    }
  }

  // 启动服务
  Future<void> _startServer() async {
    var handler = webSocketHandler((WebSocketChannel webSocket) {
      _sockets.add(webSocket);
      _log('新连接接入');
      webSocket.stream.listen((message) {
        _log('广播数据：$message');
        // 广播坐标数据
        for (var socket in _sockets) {
          if (socket != webSocket) {
            socket.sink.add(message);
          }
        }
      }, onDone: () {
        _sockets.remove(webSocket);
        _log('连接断开');
      });
    });
    try {
      _server = await shelf_io.serve(handler, InternetAddress.anyIPv4, 8080);
      _log('服务启动于 ws://$_ipInfo:8080');
    } catch (e) {
      _log('启动失败：$e');
    }
  }

  Future<void> _stopServer() async {
    await _server?.close(force: true);
    for (var s in _sockets) {
      await s.sink.close();
    }
    _sockets.clear();
    _server = null;
    _log('服务已停止');
  }

  void _log(String msg) {
    if (!mounted) return;
    setState(() {
      _logs.insert(0, '[${DateTime.now().hour}:${DateTime.now().minute}] $msg');
    });
  }

  @override
  void dispose() {
    _stopServer();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('WebSocket Server')),
      body: Column(
        children: [
          Container(
            padding: const EdgeInsets.all(20),
            color: Colors.blue[50],
            child: Column(
              children: [
                Text('本机 IP: $_ipInfo', style: const TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
                const SizedBox(height: 10),
                Row(
                  mainAxisAlignment: MainAxisAlignment.center,
                  children: [
                    ElevatedButton(
                      onPressed: _server == null ? _startServer : null,
                      child: const Text('启动服务'),
                    ),
                    const SizedBox(width: 20),
                    ElevatedButton(
                      style: ElevatedButton.styleFrom(backgroundColor: Colors.red[100]),
                      onPressed: _server != null ? _stopServer : null,
                      child: const Text('停止'),
                    ),
                  ],
                ),
              ],
            ),
          ),
          const Divider(),
          Expanded(
            child: ListView.builder(
              itemCount: _logs.length,
              itemBuilder: (context, index) => ListTile(
                leading: const Icon(Icons.info_outline, size: 16),
                title: Text(_logs[index], style: const TextStyle(fontSize: 14)),
              ),
            ),
          ),
        ],
      ),
    );
  }
}

六、总结

通过 shelf_web_socket，我们让 OpenHarmony 手机不仅仅是信息的消费者，更成为了信息的生产者和中转站。

最佳实践：

1. 异常处理：Websocket 连接很容易因网络波动断开，务必处理 onDone 和 onError。
2. 资源释放：在组件销毁或应用退出时，务必关闭 Server 和所有 Channel 连接，防止端口占用。
3. 心跳机制：为了保持连接活性，建议在应用层实现 Ping/Pong 心跳包。