在现代应用开发中，网络通信能力是不可或缺的一环。HarmonyOS 通过 @ohos.net.http 模块提供了强大的 HTTP 数据请求接口，支持 GET、POST、PUT、DELETE 等常见方法，并具备缓存、证书校验、多表单上传、数据进度监听等丰富功能。本文将全面解析该模块的使用方式、关键配置、典型示例与常见问题，助你快速构建稳定高效的网络通信功能。

---

一、模块简介

HarmonyOS 提供的 @ohos.net.http 模块，允许开发者以异步方式进行网络请求，支持多种 HTTP 方法，适用于表单提交、文件上传下载、API 数据交互等场景。

• 首次支持版本：API Version 6 起

• 支持方式：回调（Callback）或 Promise 异步方法

• 最大数据限制：默认 5MB，可手动配置至 100MB

---

二、导入方式

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

获取上下文（用于文件路径、多表单上传等）：

import { common } from '@kit.AbilityKit';

let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

---

三、基础用法示例（POST 请求）

let httpRequest = http.createHttp();

httpRequest.request("https://example.com/api/login", {
  method: http.RequestMethod.POST,
  extraData: {
    username: "admin",
    password: "123456"
  },
  header: { "Content-Type": "application/json" },
  expectDataType: http.HttpDataType.OBJECT
}, (err, data) => {
  if (!err) {
    console.info('响应结果：' + JSON.stringify(data.result));
  } else {
    console.error('请求错误：' + JSON.stringify(err));
  }
  httpRequest.destroy();
});

---

四、关键功能详解

✅ 支持的 HTTP 方法

• GET、POST、PUT、DELETE、OPTIONS、HEAD、TRACE、CONNECT

• 使用方式：

method: http.RequestMethod.GET

---

✅ 设置请求头和请求体

header: {
  "Content-Type": "application/json",
  "Accept": "application/json"
},
extraData: JSON.stringify({ name: "user" })

---

✅ 设置超时、缓存、优先级

connectTimeout: 60000,   // 连接超时（ms）
readTimeout: 60000,      // 读取超时（ms）
usingCache: true,        // 使用缓存
priority: 1              // 请求优先级（1~1000）

---

✅ 多表单上传（文件 + 文本）

multiFormDataList: [
  {
    name: "fileField",
    filePath: `${context.filesDir}/test.jpg`,
    remoteFileName: "uploaded.jpg",
    contentType: "image/jpeg"
  },
  {
    name: "desc",
    data: "这是测试上传的图片",
    contentType: "text/plain"
  }
]

---

✅ 监听响应头（headersReceive）

httpRequest.on("headersReceive", (header) => {
  console.info("响应头：" + JSON.stringify(header));
});

监听完成后别忘了关闭监听：

httpRequest.off("headersReceive");

---

✅ 使用 Promise 方式调用（推荐）

let httpRequest = http.createHttp();
httpRequest.request("https://example.com/data", {
  method: http.RequestMethod.GET
}).then(data => {
  console.info("响应：" + JSON.stringify(data.result));
  httpRequest.destroy();
}).catch(err => {
  console.error("错误：" + JSON.stringify(err));
  httpRequest.destroy();
});

---

五、流式请求（大文件或视频）

适用于接收大型数据、在线播放、多段下载等场景：

httpRequest.requestInStream("https://example.com/video", (err, code) => {
  if (!err) {
    console.info("流式请求成功，响应码：" + code);
  } else {
    console.error("流式请求失败：" + JSON.stringify(err));
  }
});

可配合以下事件监听：

• dataReceive：接收数据块

• dataEnd：接收完成

• dataReceiveProgress：接收进度

---

六、安全功能支持

✅ 客户端证书（HTTPS 双向认证）

clientCert: {
  certPath: '/path/client.pem',
  keyPath: '/path/client.key',
  certType: http.CertType.PEM,
  keyPassword: 'your-password'
}

✅ 证书锁定（Certificate Pinning）

certificatePinning: [
  {
    publicKeyHash: "SHA256-PIN1",
    hashAlgorithm: "SHA-256"
  }
]

---

七、缓存管理（缓存响应数据）

let cache = http.createHttpResponseCache(10 * 1024 * 1024); // 10MB

// 刷新缓存写入磁盘
cache.flush().then(() => console.log("缓存已刷新"));

// 删除缓存
cache.delete().then(() => console.log("缓存已清除"));

---

八、常见错误码与排查

错误码	说明
401	参数错误（字段缺失或格式不对）
201	权限拒绝（未申请网络权限）
2300006	无法解析主机名（DNS 问题）
2300007	无法连接服务器（网络断开）
2300028	操作超时
2300056	接收数据失败

💡 提示：HTTP 错误码 = 2300000 + curl 错误码。

---

九、开发建议与最佳实践

• 所有请求完成后务必执行 httpRequest.destroy() 释放资源

• 尽量使用 Promise，比回调方式更清晰易维护

• 合理使用缓存，提升性能，减少流量消耗

• 遇到跨域或连接失败问题时，可检查代理、DNS 配置等

---

🔚 总结

HarmonyOS 的 @ohos.net.http 模块功能完善，支持丰富的网络能力，从简单的 GET 请求，到复杂的多表单上传、SSL 客户端证书校验、证书锁定机制一应俱全。通过合理配置与结构化代码组织，开发者可以高效、安全地实现网络通信需求，为应用提供坚实的数据交互能力。