引言

在鸿蒙应用开发中，网络通信是最核心的能力之一。HarmonyOS 提供了多种网络编程方案：从传统的 @ohos.net.http HTTP 请求，到 @ohos.net.webSocket WebSocket 长连接，再到 @ohos.net.socket 底层 TCP/UDP Socket，以及新一代的 @kit.NetworkKit 统一网络框架。本文将从实战角度对比这四种方式，帮你选出最适合的方案。

一、HTTP 请求：@ohos.net.http

最常用的网络通信方式，适用于 RESTful API 调用、数据获取等场景。

import http from '@ohos.net.http';

async function fetchData() {
  const httpRequest = http.createHttp();

  try {
    const response = await httpRequest.request(
      'https://api.example.com/data',
      {
        method: http.RequestMethod.GET,
        header: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer your-token'
        },
        connectTimeout: 30000,
        readTimeout: 30000,
        expectDataType: http.HttpDataType.OBJECT
      }
    );

    if (response.responseCode === 200) {
      const data = JSON.parse(response.result as string);
      console.info('请求成功:', JSON.stringify(data));
      return data;
    } else {
      console.error(`HTTP错误: ${response.responseCode}`);
      return null;
    }
  } catch (err) {
    console.error('请求异常:', JSON.stringify(err));
    return null;
  } finally {
    httpRequest.destroy(); // 必须销毁，否则内存泄漏
  }
}

关键点：

• 必须调用 destroy() 释放资源，否则会造成内存泄漏
• expectDataType 可指定自动解析类型
• 支持 GET、POST、PUT、DELETE 等方法
• 超时时间建议设置合理值（默认 60s）

二、WebSocket 长连接：@ohos.net.webSocket

适用于实时推送、聊天、消息通知等场景，建立后保持连接，双向通信。

import webSocket from '@ohos.net.webSocket';

class WebSocketClient {
  private ws: webSocket.WebSocket;

  connect(url: string): Promise {
    return new Promise((resolve, reject) => {
      this.ws = webSocket.createWebSocket();

      // 连接成功
      this.ws.on('open', () => {
        console.info('WebSocket 连接已建立');
        resolve();
      });

      // 收到消息
      this.ws.on('message', (data: string | ArrayBuffer) => {
        const msg = typeof data === 'string'
          ? JSON.parse(data)
          : new TextDecoder().decode(data);
        console.info('收到消息:', JSON.stringify(msg));
        this.onMessage?.(msg);
      });

      // 连接关闭
      this.ws.on('close', (code: number, reason: string) => {
        console.info(`连接关闭: code=${code}, reason=${reason}`);
        this.onClose?.(code, reason);
        // 可选：自动重连
        setTimeout(() => this.connect(url), 3000);
      });

      // 连接出错
      this.ws.on('error', (err) => {
        console.error('WebSocket 错误:', JSON.stringify(err));
        reject(err);
      });

      this.ws.connect(url, (err) => {
        if (err) reject(err);
      });
    });
  }

  send(data: object) {
    this.ws.send(JSON.stringify(data));
  }

  close() {
    this.ws.close();
  }

  onMessage: ((msg: any) => void) | null = null;
  onClose: ((code: number, reason: string) => void) | null = null;
}

关键点：

• WebSocket 连接后需正确处理重连机制
• 心跳检测必不可少：每 30-60s 发送 ping 帧
• 支持 string 和 ArrayBuffer 两种消息格式
• 应用退出前必须 close() 释放连接

三、Socket 通信：@ohos.net.socket

适用于 TCP/UDP 底层通信，如 IoT 设备控制、游戏实时对战、自定义协议等。

TCP 客户端示例

import socket from '@ohos.net.socket';
import { BusinessError } from '@ohos.base';

class TcpClient {
  private tcp: socket.TcpSocket;

  constructor() {
    this.tcp = socket.constructTCPSocket();
  }

  connect(host: string, port: number): Promise {
    return new Promise((resolve, reject) => {
      this.tcp.on('connect', () => {
        console.info('TCP 连接建立');
        resolve();
      });

      this.tcp.on('message', (data: ArrayBuffer) => {
        const msg = new TextDecoder().decode(data);
        console.info('收到 TCP 数据:', msg);
        this.onData?.(msg);
      });

      this.tcp.on('error', (err: BusinessError) => {
        console.error('TCP 错误:', err.message);
        reject(err);
      });

      this.tcp.connect({
        address: { address: host, port },
        timeout: 10000
      });
    });
  }

  send(data: string) {
    this.tcp.send({
      data: new TextEncoder().encode(data).buffer
    });
  }

  close() {
    this.tcp.close();
  }

  onData: ((data: string) => void) | null = null;
}

UDP 示例

class UdpClient {
  private udp: socket.UDPSocket;

  constructor() {
    this.udp = socket.constructUDPSocketInstance();
  }

  bind(port: number): Promise {
    return new Promise((resolve) => {
      this.udp.on('message', (data: { message: ArrayBuffer, remoteInfo: socket.SocketRemoteInfo }) => {
        const msg = new TextDecoder().decode(data.message);
        console.info(`UDP 收到来自 ${data.remoteInfo.address}:${data.remoteInfo.port}: ${msg}`);
        this.onMessage?.(msg, data.remoteInfo);
      });

      this.udp.bind({ address: '0.0.0.0', port }, () => {
        console.info(`UDP 绑定端口 ${port}`);
        resolve();
      });
    });
  }

  send(msg: string, host: string, port: number) {
    this.udp.send({
      data: new TextEncoder().encode(msg).buffer,
      address: { address: host, port }
    });
  }

  close() {
    this.udp.close();
  }

  onMessage: ((msg: string, remote: socket.SocketRemoteInfo) => void) | null = null;
}

四、@kit.NetworkKit 统一网络框架（API 12+）

HarmonyOS NEXT 推荐的新一代网络框架，统一了 HTTP 和 WebSocket，提供更简洁的 API。

import { network } from '@kit.NetworkKit';

// 检查网络状态
network.getDefaultNet().then(net => {
  net.on('netAvailable', () => {
    console.info('网络已连接');
  });

  net.on('netUnavailable', () => {
    console.info('网络不可用');
  });

  net.on('netCapabilitiesChange', (capabilities) => {
    console.info('网络能力变化:', JSON.stringify(capabilities));
  });
});

// 监听网络状态变化（替代旧版 @ohos.net.connection）
function monitorNetwork() {
  const netHandle = network.getDefaultNetSync();
  console.info(`当前网络类型: ${netHandle.netType}`);

  // 获取 IP 信息
  const addresses = netHandle.getAddressesByName('example.com');
  addresses.forEach(addr => {
    console.info(`解析地址: ${addr.address}:${addr.port}`);
  });
}

五、四种方式对比

特性	@ohos.net.http	@ohos.net.webSocket	@ohos.net.socket	@kit.NetworkKit
传输层	HTTP/HTTPS	WebSocket	TCP/UDP	统一封装
数据格式	JSON/文本	文本/二进制	二进制	自动适配
连接方式	短连接	长连接	自定义	智能选路
适用场景	API 调用	实时推送	IoT/游戏	通用场景
开发难度	⭐	⭐⭐	⭐⭐⭐	⭐
实时性	低	高	最高	中
可靠性	高	中（需重连）	低（需自己处理）	高
推荐指数	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐

六、最佳实践总结

1. 网络请求封装

// 统一请求拦截器思想
class HttpInterceptor {
  static async request(config: HttpConfig): Promise> {
    const start = Date.now();
    try {
      const res = await httpRequest(config);
      console.info(`[NET] ${config.method} ${config.url} ${Date.now() - start}ms`);
      return { code: 0, data: res.data as T };
    } catch (err) {
      console.error(`[NET] ${config.url} 失败:`, err);
      return { code: -1, message: '网络异常' };
    }
  }
}

2. 选择合适的方案

• 数据 CRUD → @ohos.net.http
• 即时通讯 / 推送 → @ohos.net.webSocket + 心跳
• 设备控制 / 游戏 → @ohos.net.socket (TCP/UDP)
• 鸿蒙 NEXT 新项目 → @kit.NetworkKit

3. 注意事项

• 网络请求需在 module.json5 中声明 ohos.permission.INTERNET 权限
• 主线程不可做网络请求，必须使用异步 API
• 大文件下载推荐使用 @ohos.net.http 的流式下载 + 断点续传
• 生产环境务必实现请求重试 + 指数退避

结语

HarmonyOS 的网络编程方案丰富而灵活。对于大多数应用场景，@ohos.net.http 配合 @ohos.net.webSocket 组合足以应对；对于 IoT 和游戏类高性能场景，@ohos.net.socket 提供更底层的控制。而 @kit.NetworkKit 则是面向未来的统一方案，建议新项目优先考虑。掌握这四种方式，你就能在鸿蒙开发中游刃有余地处理各种网络通信需求。