本文献给：

已掌握鸿蒙基础 UI 与页面导航、希望为自己的应用接入网络能力的开发者。网络通信是移动应用的命脉，HarmonyOS 的 Network Kit 提供了从基础的 HTTP 请求到全双工的 WebSocket 和原生 Socket 等一系列能力。本文将系统讲解如何使用 @ohos.net.http 发起数据请求、如何集成第三方库 Axios、以及如何利用 TCP Socket 和 WebSocket 实现实时通信，帮助你构建稳定高效的网络层。

你将学到：

1. 使用 @ohos.net.http 发起 GET/POST 请求并处理响应
2. 在鸿蒙项目中集成并使用 Axios（@ohos/axios）
3. 基于 @ohos.net.socket 的 TCP Socket 通信
4. 使用 @ohos.net.webSocket 实现 WebSocket 双向通信
5. 网络请求中的权限配置与常见安全注意事项

---

一、网络权限与基础准备

在进行任何网络操作之前，必须在 module.json5 中声明网络权限和（如果需要）清除文本流量限制。

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

• ohos.permission.INTERNET：允许应用访问网络（必选）。
• ohos.permission.GET_NETWORK_INFO：允许获取网络连接信息（可选，但建议配置）。

另外，若需访问 HTTP 明文链接（非 HTTPS），还需在 module.json5 的顶层或 Ability 配置中增加 network 段，将 cleartextTraffic 设为 true（开发调试用，正式上线建议使用 HTTPS）。

二、HTTP 数据请求 —— @ohos.net.http

2.1 发起 GET 请求

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

// 每个 httpRequest 实例对应一次请求
let httpRequest = http.createHttp();

httpRequest.request(
  'https://api.example.com/data',
  {
    method: http.RequestMethod.GET,
    header: {
      'Content-Type': 'application/json'
    }
  }
).then((response) => {
  if (response.responseCode === 200) {
    // response.result 是 ArrayBuffer 类型，需转为字符串
    let data = new TextDecoder().decode(new Uint8Array(response.result as ArrayBuffer));
    console.log('GET 成功:', data);
  }
}).catch((err) => {
  console.error('GET 失败:', JSON.stringify(err));
}).finally(() => {
  httpRequest.destroy(); // 释放资源
});

关键点：

• 使用 http.createHttp() 创建请求对象，每个对象发起一次请求，结束后必须调用 destroy() 释放。
• 响应体 response.result 是 ArrayBuffer，需要用 TextDecoder 或手动转成字符串 / JSON。
• 支持可选字段 expectDataType 指定返回类型（如 http.HttpDataType.STRING），可省略手动转换。

2.2 发起 POST 请求（携带 JSON Body）

let httpRequest = http.createHttp();

let requestBody = JSON.stringify({
  username: 'alice',
  password: '123456'
});

httpRequest.request(
  'https://api.example.com/login',
  {
    method: http.RequestMethod.POST,
    header: {
      'Content-Type': 'application/json'
    },
    extraData: requestBody, // POST 体
    expectDataType: http.HttpDataType.STRING // 直接返回字符串
  }
).then((response) => {
  console.log('登录结果:', response.result);
}).catch((err) => {
  console.error('登录失败:', JSON.stringify(err));
}).finally(() => {
  httpRequest.destroy();
});

2.3 上传文件

使用 extraData 可以传递 FormData 格式或 ArrayBuffer，配合 multipart/form-data 进行文件上传。

import fileIo from '@ohos.file.fs';

let httpRequest = http.createHttp();
let fileData = fileIo.readSync('test.png'); // 示例，实际应为异步读取

httpRequest.request(
  'https://api.example.com/upload',
  {
    method: http.RequestMethod.POST,
    header: {
      'Content-Type': 'multipart/form-data'
    },
    extraData: fileData
  }
).then((response) => {
  console.log('上传成功');
}).catch((err) => {
  console.error('上传失败:', JSON.stringify(err));
}).finally(() => {
  httpRequest.destroy();
});

三、第三方库 Axios

在传统前端开发中，Axios 是最常用的 HTTP 客户端库。鸿蒙官方提供了适配版本 @ohos/axios，接口设计与 Web 版基本一致，可极大降低迁移成本。

3.1 安装与基本用法

在 DevEco Studio 中，打开 oh-package.json5（位于工程或模块根目录），在 dependencies 中添加：

{
  "dependencies": {
    "@ohos/axios": "^2.0.0"
  }
}

点击 Sync Now 同步依赖后，即可导入使用：

import axios from '@ohos/axios';

axios.get('https://api.example.com/data')
  .then((response) => {
    console.log('Axios 返回:', response.data);
  })
  .catch((error) => {
    console.error('Axios 出错:', error);
  });

Axios 自动将响应数据解析为 JSON 对象，无需手动处理 ArrayBuffer，开发体验更好。

3.2 创建实例与拦截器

通过自定义实例可统一设置 baseURL、超时、请求/响应拦截器。

import axios, { AxiosRequestConfig, AxiosResponse } from '@ohos/axios';

// 创建实例
const instance = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 5000
});

// 请求拦截器：携带 Token
instance.interceptors.request.use((config: AxiosRequestConfig) => {
  config.headers['Authorization'] = 'Bearer your_token';
  return config;
});

// 响应拦截器：统一错误处理
instance.interceptors.response.use(
  (response: AxiosResponse) => {
    if (response.status !== 200) {
      console.error('请求异常:', response.data);
    }
    return response;
  },
  (error) => {
    console.error('网络错误:', JSON.stringify(error));
    return Promise.reject(error);
  }
);

// 使用实例
instance.get('/user/profile').then(res => console.log(res.data));

3.3 Axios vs 原生 http

特性	@ohos.net.http	@ohos/axios
自动 JSON 解析	需手动转换	自动解析
拦截器	不支持	支持请求/响应拦截
取消请求	通过 destroy()	支持 AbortController / CancelToken
API 风格	单一请求对象	Promise + 配置链式调用
体积	系统内置	需额外引入，增加包体积

对于简单的单次请求，原生 http 足够；对于需要 Token 管理、统一错误处理、链式调用的场景，推荐使用 Axios。

四、Socket 通信 —— @ohos.net.socket

HarmonyOS 提供了 TCP Socket 客户端能力（不支持直接创建服务器），适用于与 TCP 服务器进行原生通信，如物联网设备控制、自定义协议聊天等。

4.1 创建 TCP 连接

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

let tcp = socket.constructTCPSocketInstance();

let bindAddress: socket.NetAddress = {
  address: '192.168.1.100',
  port: 8888,
  family: 1  // 1 表示 IPv4
};

tcp.connect(bindAddress).then(() => {
  console.log('TCP 连接成功');
}).catch((err) => {
  console.error('TCP 连接失败:', JSON.stringify(err));
});

4.2 发送与接收数据

发送数据需要将字符串转为 ArrayBuffer：

let message = 'Hello, server!';
let encoder = new TextEncoder();
let sendBuf = encoder.encode(message).buffer as ArrayBuffer;

tcp.send({ data: sendBuf }).then(() => {
  console.log('消息已发送');
});

// 接收数据
tcp.on('message', (value: { data: ArrayBuffer, remoteInfo: socket.SocketRemoteInfo }) => {
  let decoder = new TextDecoder();
  let recvStr = decoder.decode(new Uint8Array(value.data));
  console.log('收到服务端:', recvStr);
});

4.3 关闭与异常处理

tcp.on('close', () => {
  console.log('TCP 连接关闭');
});

tcp.on('error', (err) => {
  console.error('TCP 错误:', JSON.stringify(err));
});

// 主动关闭
tcp.close().catch((err) => {
  console.error('关闭失败:', err);
});

注意事项：

• TCP Socket 是客户端，需要服务端地址。
• 需要在 module.json5 中声明 ohos.permission.INTERNET。
• 发送和接收均异步，注意数据粘包/拆包问题，需自行定义应用层协议。

五、WebSocket 通信 —— @ohos.net.webSocket

WebSocket 提供全双工、低延迟的实时通信能力，适合聊天、消息推送、协同编辑等场景。

5.1 建立连接

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

let ws = webSocket.createWebSocket();

ws.connect('wss://echo.websocket.org').then((ok, message) => {
  console.log('WebSocket 连接成功:', message);
}).catch((err) => {
  console.error('WebSocket 连接失败:', JSON.stringify(err));
});

注意：API 不同版本略有差异。上述为基本形式，返回 Promise。

5.2 收发消息

ws.on('open', (err, value) => {
  console.log('连接已打开');
  // 发送文本消息
  ws.send('Hello WebSocket!', (err, value) => {
    if (!err) console.log('发送成功');
  });
});

ws.on('message', (err, value) => {
  // value 为 string 或 ArrayBuffer
  console.log('收到消息:', value);
});

ws.on('error', (err) => {
  console.error('WebSocket 错误:', JSON.stringify(err));
});

5.3 心跳保持与关闭

为避免长连接被中间设备关闭，可定时发送心跳包：

let heartbeatTimer: number | null = null;

ws.on('open', () => {
  // 每 30 秒发送 ping
  heartbeatTimer = setInterval(() => {
    ws.send('ping', (err) => {
      if (err) console.error('心跳发送失败');
    });
  }, 30000);
});

// 关闭连接前清除定时器
function closeConnection() {
  if (heartbeatTimer) clearInterval(heartbeatTimer);
  ws.close((err) => {
    if (err) console.error('关闭失败:', err);
    else console.log('WebSocket 已关闭');
  });
}

六、常见错误与注意事项

6.1 忘记声明网络权限

INTERNET 权限是任何网络请求的前提，缺失会导致 Error: Permission denied。务必在 module.json5 中配置。

6.2 HTTP 明文访问被拦截

默认禁止 HTTP 明文请求，若需要，在 module.json5 中设置：

"network": {
  "cleartextTraffic": true
}

但发布上架时需移除，改用 HTTPS。

6.3 httpRequest 未销毁导致资源泄漏

每次 http.createHttp() 都会创建新对象，用完需 destroy()。在 finally 块中调用最安全。

6.4 TCP 数据粘包

Socket 接收端可能一次收到多条消息的拼接，需要根据协议进行拆分（如固定长度头、分隔符等）。应用层需自行实现分包逻辑。

6.5 WebSocket 重连机制

网络波动可能导致 WebSocket 断开。需在 on('close') 或 on('error') 中实现指数退避重连，避免频繁重试。

6.6 Axios 版本兼容性

使用 @ohos/axios 时，注意其版本与 HarmonyOS API 的兼容性，建议使用最新稳定版并参考官方示例。

七、小结

通信方式	使用模块 / 库	适用场景
HTTP 请求	@ohos.net.http	REST API 调用、文件上传
HTTP 请求（增强）	@ohos/axios	需要拦截器、统一错误处理、Token 管理的复杂网络层
TCP Socket	@ohos.net.socket	自定义协议通信、物联网设备控制
WebSocket	@ohos.net.webSocket	实时推送、聊天、在线协作

掌握这四种网络通信方式后，你可以根据业务需求选择最合适的方案，构建高效稳健的网络层。无论是简单数据获取还是复杂的实时双向交互，HarmonyOS 的网络能力都能为你提供可靠支撑。

---

觉得文章有帮助？别忘了：

👍 点赞 👍 – 给我一点鼓励
⭐ 收藏 ⭐ – 方便以后查看
🔔 关注 🔔 – 获取更新通知

---

标签： #HarmonyOS #NetworkKit #HTTP请求 #Axios #Socket通信 #WebSocket #学习笔记 #鸿蒙开发