HarmonyOS 网络连接 —— HTTP 请求、Axios 与 Socket 通信

烛衔溟2026-08-05 9:25

本文献给：

已掌握鸿蒙基础 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. 网络请求中的权限配置与常见安全注意事项

目录

  • 一、网络权限与基础准备
  • [二、HTTP 数据请求 ------ `@ohos.net.http`](#二、HTTP 数据请求 —— @ohos.net.http)
    • [2.1 发起 GET 请求](#2.1 发起 GET 请求)
    • [2.2 发起 POST 请求（携带 JSON Body）](#2.2 发起 POST 请求（携带 JSON Body）)
    • [2.3 上传文件](#2.3 上传文件)
  • [三、第三方库 Axios](#三、第三方库 Axios)
    • [3.1 安装与基本用法](#3.1 安装与基本用法)
    • [3.2 创建实例与拦截器](#3.2 创建实例与拦截器)
    • [3.3 Axios vs 原生 http](#3.3 Axios vs 原生 http)
  • [四、Socket 通信 ------ `@ohos.net.socket`](#四、Socket 通信 —— @ohos.net.socket)
    • [4.1 创建 TCP 连接](#4.1 创建 TCP 连接)
    • [4.2 发送与接收数据](#4.2 发送与接收数据)
    • [4.3 关闭与异常处理](#4.3 关闭与异常处理)
  • [五、WebSocket 通信 ------ `@ohos.net.webSocket`](#五、WebSocket 通信 —— @ohos.net.webSocket)
    • [5.1 建立连接](#5.1 建立连接)
    • [5.2 收发消息](#5.2 收发消息)
    • [5.3 心跳保持与关闭](#5.3 心跳保持与关闭)
  • 六、常见错误与注意事项
    • [6.1 忘记声明网络权限](#6.1 忘记声明网络权限)
    • [6.2 HTTP 明文访问被拦截](#6.2 HTTP 明文访问被拦截)
    • [6.3 httpRequest 未销毁导致资源泄漏](#6.3 httpRequest 未销毁导致资源泄漏)
    • [6.4 TCP 数据粘包](#6.4 TCP 数据粘包)
    • [6.5 WebSocket 重连机制](#6.5 WebSocket 重连机制)
    • [6.6 Axios 版本兼容性](#6.6 Axios 版本兼容性)
  • 七、小结

一、网络权限与基础准备

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

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 请求

typescript 复制代码 
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）

typescript 复制代码 
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 进行文件上传。

typescript 复制代码 
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 中添加：

json5 复制代码 
{
  "dependencies": {
    "@ohos/axios": "^2.0.0"
  }
}

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

typescript 复制代码 
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、超时、请求/响应拦截器。

typescript 复制代码 
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 连接

typescript 复制代码 
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：

typescript 复制代码 
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 关闭与异常处理

typescript 复制代码 
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 建立连接

typescript 复制代码 
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 收发消息

typescript 复制代码 
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 心跳保持与关闭

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

typescript 复制代码 
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 中设置：

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 #学习笔记 #鸿蒙开发

相关推荐
kaixin_啊啊2 小时前
群晖部署Vaultwarden：HTTPS访问、自动填充与密码迁移
网络协议·http·https
懿路向前3 小时前
【HarmonyOS学习笔记】2026-08-04 | 端插件新装饰器与CreateRecord全链路验证
笔记·学习·harmonyos
云端漫步19873 小时前
HarmonyOS NEXT AI 智能生活助手：AI 翻译助手
人工智能·华为·生活·harmonyos
世人万千丶10 小时前
鸿蒙日志体系高级应用：HiLog分级输出/隐私脱敏/远程日志采集/线上问题精准溯源方案
学习·harmonyos·鸿蒙
程序员黑豆16 小时前
鸿蒙应用开发：AttributeModifier 使用教程
前端·harmonyos
HarmonyOS_SDK17 小时前
基于人体骨骼点识别与跟踪，实现低时延体感游戏
harmonyos
世人万千丶18 小时前
鸿蒙Crash高级捕获与异常监控：全局异常兜底/崩溃栈解析/符号表还原/智能聚类/闭环修复
学习·机器学习·华为·数据挖掘·harmonyos·鸿蒙·聚类
云端漫步198719 小时前
HarmonyOS NEXT AI 智能生活助手：创建企业级 AI 工程与目录结构
人工智能·生活·harmonyos
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）04Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费05AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片0900 Debian字符界面如何支持中文10历年考研数学一、数学二、数学三真题试卷及答案PDF