鸿蒙三方库httpclient使用

简介

httpclient已支持的特性参考httpclient官方文档简介。

安装配置

安装

通过如下两种方式设置三方包依赖信息(OpenHarmony ohpm环境配置等更多内容，请参考如何安装 OpenHarmony ohpm包)：

方式一：在Terminal窗口中，执行如下命令安装三方包，DevEco Studio会自动在工程的oh-package.json5中自动添加三方包依赖。

ohpm install @ohos/lottie
方式二：在工程的oh-package.json5中设置三方包依赖，配置示例如下：

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

依赖设置完成后，需要执行ohpm install命令安装依赖包，依赖包会存储在工程的oh_modules目录下。

复制代码

ohpm install

添加权限

在module.json5中添加网络请求权限。

复制代码

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

导入模块

在需要使用的 .ets 文件中导入模块

复制代码

import { HttpClient, Request, Response, TimeUnit } from '@ohos/httpclient';

使用流程

1.创建 HttpClient 实例并配置

建议使用构建器模式来创建 HttpClient 实例，并设置全局配置（如超时时间）。

TypeScript 复制代码

// 创建 HttpClient 实例，可设置连接和读取超时时间[citation:6]
private client: HttpClient = new HttpClient.Builder()
  .setConnectTimeout(10, TimeUnit.SECONDS) // 设置连接超时时间[citation:6]
  .setReadTimeout(10, TimeUnit.SECONDS) // 设置读取超时时间[citation:6]
  .build();

连接超时时间和读取超时时间

在网络请求中，连接超时时间 和读取超时时间是两个关键但不同的概念，它们分别控制着请求过程中不同阶段的等待时间。

核心区别对比

超时类型	控制阶段	类比场景	典型值设置
连接超时	从发起请求到建立连接的阶段	像拨号等待对方接电话的时间	5-15秒
读取超时	连接建立后数据传输的阶段	像电话接通后等待对方说话的时间	10-30秒

连接超时 (Connection Timeout)

作用阶段：从发起网络请求到与服务器成功建立TCP连接的整个过程。

包含的具体步骤：

DNS域名解析
TCP三次握手
SSL/TLS握手（HTTPS请求）
等待服务器接受连接

读取超时 (Read Timeout)

作用阶段：连接建立成功后，等待服务器返回数据的整个过程。

包含的具体步骤：

等待服务器处理请求
服务器生成响应数据
数据从服务器传输到客户端

合理配置建议

业务场景	连接超时	读取超时	理由
实时聊天	5秒	10秒	需要快速响应，用户体验敏感
文件下载	10秒	60+秒	连接要稳定，传输可以慢
API接口调用	10秒	30秒	平衡稳定性和响应速度
图片加载	8秒	20秒	中等负载，需要较快响应

2.构建请求对象 (Request)

使用 Request.Builder() 来构建你的请求，设置 URL、请求方法、请求头等信息。

TypeScript 复制代码

// 构建一个 GET 请求
let request = new Request.Builder()
  .get("https://api.example.com/data") // 指定请求方法和URL
  .addHeader("Content-Type", "application/json") // 添加请求头
  .params("key1", "value1") // 添加URL参数（针对GET请求）
  .params("key2", "value2")
  .build();
  
// 构建一个 POST 请求
let requestBody = httpclient.RequestBody.create(JSON.stringify({
    "data1": "value1",
    "data2": "value2"
}));
let postRequest = new Request.Builder()
    .url("https://api.example.com/submit")
    .post(requestBody) // 设置请求方法为POST并传入请求体
    .addHeader("Content-Type", "application/json")
    .build();

3.发起请求与处理响应

HttpClient 提供了 enqueue (异步) 和 execute (同步) 方法来发起请求。

异步请求 (enqueue) ：推荐在 UI 线程中使用，避免阻塞界面。

TypeScript 复制代码

this.client.newCall(request).enqueue((result: Response) => {
  // 成功回调
  if (result && result.result) {
    console.info("请求成功，返回数据: " + result.result);
    // 注意：result.result 通常是字符串，如果是JSON需要手动解析
    // let jsonObj = JSON.parse(result.result);
  }
}, (error: BusinessError) => {
  // 失败回调
  console.error("请求失败: " + JSON.stringify(error));
});

同步请求 (execute) ：需要注意，同步请求会阻塞当前线程 ，在 UI 线程中使用可能导致应用无响应（ANR），因此通常建议在非 UI 线程（例如使用 TaskPool 或 Worker ）中执行。
TypeScript 复制代码
```
try {
  const response = await this.client.newCall(request).execute();
  console.info("同步请求结果: " + response.result);
} catch (error) {
  console.error("同步请求错误: " + error);
}
```

进阶用法

待整理

拦截器 (Interceptors)

文件上传与下载

表单提交

核心注意事项

线程选择：
- 严禁在主线程（UI 线程）中执行同步的 execute() 方法，这会导致界面卡顿甚至无响应。
- 异步请求 enqueue() 是 UI 线程中的首选方式。
- 如果必须在后台执行同步请求或耗时网络操作，请使用 TaskPool 或 Worker。
数据解析：
- 请求返回的 result 字段通常是字符串类型 。如果服务器返回的是 JSON 格式的数据，你需要手动使用 JSON.parse() 进行解析。
资源释放：
- 虽然 @ohos/httpclient 本身管理了连接资源，但确保请求完成后，特别是使用同步请求时，没有不必要的对象引用，以利于垃圾回收。

鸿蒙三方库httpclient使用

简介

安装配置

安装

添加权限

导入模块

使用流程

1.创建 HttpClient 实例并配置

连接超时时间和读取超时时间

核心区别对比

连接超时 (Connection Timeout)

读取超时 (Read Timeout)

合理配置建议

2.构建请求对象 (Request)

3.发起请求与处理响应

进阶用法

拦截器 (Interceptors)

文件上传与下载

表单提交

Cookie 管理

核心注意事项