当前位置：首页 > news >正文

鸿蒙三方库httpclient使用

news 2025/11/8 10:13:35

简介

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 实例，并设置全局配置（如超时时间）。

// 创建 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、请求方法、请求头等信息。

// 构建一个 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 线程中使用，避免阻塞界面。

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 ）中执行。
```
try {const response = await this.client.newCall(request).execute();console.info("同步请求结果: " + response.result);
} catch (error) {console.error("同步请求错误: " + error);
}
```

进阶用法

待整理

拦截器 (Interceptors)

文件上传与下载

表单提交

Cookie 管理

核心注意事项

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