鸿蒙 ArkTS 网络请求封装与错误处理:从 @ohos.net.http 到可复用的 HttpClient 实战
前言:为什么每个鸿蒙应用都需要一个网络层
刚开始用 ArkTS 写鸿蒙应用时,很多人都是在一个页面里直接写 http.createHttp(),发完请求就 JSON.parse,出错了就弹一个提示。功能跑通之后再看代码,同一个 GET 请求在三个页面里写了三遍,超时时间各不相同,401 要不要跳登录全凭当时的心情,出了问题只能靠猜。等到接口一多、页面一多,这样的代码就成了谁也不敢动的“祖传代码”。
本文要做的,就是把网络请求从页面里抽出来,封装成一个可复用的 HttpClient:统一超时、统一重试、统一错误分类、统一解析业务码。读完本文,你可以直接把文中的三份代码文件复制到自己的工程里使用,也可以按自己的后端约定改一改再用。文章基于 HarmonyOS API 12 以上、ArkTS 语言,使用的核心能力是 @ohos.net.http。
一、先看鸿蒙网络请求的三个特点
1. 请求实例要显式创建和销毁
与浏览器里的 fetch 不同,鸿蒙的 http 模块没有全局可用的请求函数,必须先 http.createHttp() 得到一个实例,请求完成后再调用 destroy()。如果只创建不销毁,连接资源会一直占用,页面反复进出几次之后,应用就可能出现请求越来越慢、甚至新建请求失败的情况。这一点是封装时最容易被忽略、也最值得先写进 finally 里的规则。
2. 超时是配置项,不是靠自己计时
@ohos.net.http 的 HttpRequestOptions 提供了 connectTimeout 与 readTimeout 两个字段,单位都是毫秒。把它们配好,网络卡住时请求会在指定时间后自动中断并抛错,不需要自己再写一个定时器去“掐表”。在弱网环境下,这两个值建议分别设为 8000 毫秒与 15000 毫秒左右,既不会让用户等太久,也不会因为一次短暂抖动就直接失败。
3. ArkTS 的类型检查会帮你,也会拦你
ArkTS 是强类型语言,JSON.parse 返回的是 Object 类型,不能直接当作业务对象使用;catch (e) 里的 e 在严格模式下是 unknown,不能直接读 e.code。封装时要把这些类型问题一次性处理好:定义好响应体泛型、定义好错误类型,调用方拿到手的就是类型安全的 data,而不是到处都要 as 一下的 any。
二、封装的整体设计:三层分工
一个好用的网络层只需要三层,每层只做一件事:
| 层 | 文件 | 职责 |
|---|---|---|
| 错误类型层 | HttpError.ets |
定义网络错误与业务错误,说明错误是否可重试 |
| 请求执行层 | HttpClient.ets |
发请求、管超时、做重试、解析响应、销毁实例 |
| 页面调用层 | Index.ets 等页面 |
只关心成功拿数据、失败给提示,不碰底层细节 |
分层的最大好处是改动有边界:后端把业务码从 0 改成 200,只需要改请求执行层的一个判断;想把重试策略从“固定间隔”改成“指数退避”,也只需要改同一个文件;页面代码一行都不用动。
设计原则:页面不应该知道
http.createHttp的存在;HttpClient不应该知道任何一个具体业务字段的名字。
三、第一步:先把错误分清楚——HttpError.ets
很多封装一上来就写请求函数,结果错误处理只能靠字符串匹配。正确顺序是先定义错误:一次请求可能失败在两个地方,一是网络层,二是业务层,二者的处理方式完全不同。网络层失败通常可以重试,业务层失败重试也没有用。
// HttpError.ets —— 统一错误类型定义
export class NetworkError extends Error {
statusCode: number = 0;
retryable: boolean = true;
constructor(message: string, statusCode: number = 0, retryable: boolean = true) {
super(message);
this.name = 'NetworkError';
this.statusCode = statusCode;
this.retryable = retryable;
}
}
export class BusinessError extends Error {
code: number = -1;
raw: string = '';
constructor(message: string, code: number, raw: string = '') {
super(message);
this.name = 'BusinessError';
this.code = code;
this.raw = raw;
}
}
这样定义有三个好处。第一,调用方可以用 instanceof 区分错误类型,不用再解析错误文案。第二,NetworkError 自带 retryable 字段,重试逻辑不需要再去判断状态码:超时和 5xx 设为 true,404 这类客户端错误设为 false。第三,BusinessError 保留了原始响应体 raw,因为业务错误往往还带有“剩余次数”“需要补充的信息”等附加字段,页面可能要拿来展示。
错误分类的决策可以画成一张简单的流程图:请求发出后,先看网络层是否成功,失败就归为网络错误;网络成功再看 HTTP 状态码,非 2xx 同样是网络错误;状态码正常再解析 JSON,解析失败按网络错误处理;最后检查业务码,非成功码就是业务错误。按这个顺序走,任何一次失败都有且只有一个归属,不会出现既像网络错又像业务错的模糊地带。
四、第二步:核心请求工具——HttpClient.ets
下面是本文的核心代码。HttpClient 只暴露 get 与 post 两个静态方法,内部的 request 方法负责重试循环,doRequest 方法负责一次真实的网络请求。
// HttpClient.ets —— 带超时、重试、统一错误处理的网络请求工具
import http from '@ohos.net.http';
import { NetworkError, BusinessError } from './HttpError';
export interface HttpResponse<T> {
data: T;
code: number;
message: string;
}
export interface RequestOptions {
timeout?: number;
maxRetries?: number;
headers?: Record<string, string>;
successCode?: number;
}
export class HttpClient {
private static readonly DEFAULT_TIMEOUT: number = 8000;
private static readonly DEFAULT_RETRIES: number = 2;
static async get<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>> {
return HttpClient.request<T>(url, 'GET', undefined, options);
}
static async post<T>(url: string, body: string, options?: RequestOptions): Promise<HttpResponse<T>> {
return HttpClient.request<T>(url, 'POST', body, options);
}
private static async request<T>(url: string, method: string, body: string | undefined, options?: RequestOptions): Promise<HttpResponse<T>> {
const maxRetries: number = options?.maxRetries ?? HttpClient.DEFAULT_RETRIES;
let lastError: Error | undefined = undefined;
for (let attempt: number = 0; attempt <= maxRetries; attempt++) {
try {
return await HttpClient.doRequest<T>(url, method, body, options);
} catch (err) {
lastError = err as Error;
if (err instanceof BusinessError) {
throw err;
}
if (err instanceof NetworkError && !err.retryable) {
throw err;
}
if (attempt < maxRetries) {
await HttpClient.sleep(1000 * Math.pow(2, attempt));
}
}
}
throw lastError;
}
private static async doRequest<T>(url: string, method: string, body: string | undefined, options?: RequestOptions): Promise<HttpResponse<T>> {
const httpRequest: http.HttpRequest = http.createHttp();
try {
const response: http.HttpResponse = await httpRequest.request(url, {
method: method as http.RequestMethod,
header: options?.headers ?? { 'Content-Type': 'application/json' },
extraData: body,
connectTimeout: options?.timeout ?? HttpClient.DEFAULT_TIMEOUT,
readTimeout: 15000,
expectDataType: http.HttpDataType.STRING
});
if (response.responseCode < 200 || response.responseCode >= 300) {
throw new NetworkError('HTTP ' + response.responseCode, response.responseCode, response.responseCode >= 500);
}
let parsed: Record<string, Object>;
try {
parsed = JSON.parse(response.result as string) as Record<string, Object>;
} catch (e) {
throw new NetworkError('响应不是合法 JSON', response.responseCode, true);
}
const successCode: number = options?.successCode ?? 0;
const code: number = parsed['code'] as number;
if (code !== successCode) {
throw new BusinessError((parsed['message'] as string) ?? '业务处理失败', code, response.result as string);
}
return { data: parsed['data'] as T, code: code, message: parsed['message'] as string };
} finally {
httpRequest.destroy();
}
}
private static sleep(ms: number): Promise<void> {
return new Promise<void>((resolve: () => void) => {
setTimeout(() => { resolve(); }, ms);
});
}
}
这段代码里有五个值得逐行理解的点。第一,重试用 for 循环而不是递归,次数清晰、不会栈溢出。第二,业务错误一旦出现就立即抛出,因为令牌过期、参数错误这类问题重试多少次结果都一样。第三,等待时间是指数退避,第一次重试等 1 秒、第二次等 2 秒、第三次等 4 秒,避免在服务端已经过载时用密集重试雪上加霜。第四,finally 里一定调用 destroy(),这是鸿蒙 http 模块最容易踩的坑。第五,JSON 解析失败被归为网络错误,因为服务端偶尔会返回 Nginx 的 HTML 错误页,这种情况换一次请求可能就好了。
五、第三步:在 ArkUI 页面里调用——Index.ets
封装做得再好,页面调用起来麻烦也是白搭。下面这份页面代码只做三件事:点按钮时把 loading 置为 true,成功时把数据写进 @State,失败时按错误类型给不同的提示。
// Index.ets —— ArkUI 页面中调用 HttpClient
import { HttpClient, HttpResponse } from './HttpClient';
import { NetworkError, BusinessError } from './HttpError';
interface UserInfo {
nickname: string;
avatar: string;
}
@Entry
@Component
struct Index {
@State userInfo: UserInfo | null = null;
@State loading: boolean = false;
@State errorMessage: string = '';
private async fetchUserInfo(): Promise<void> {
this.loading = true;
this.errorMessage = '';
try {
const res: HttpResponse<UserInfo> = await HttpClient.get<UserInfo>('https://api.example.com/user/info', { timeout: 8000, maxRetries: 3 });
this.userInfo = res.data;
} catch (err) {
if (err instanceof NetworkError) {
if (err.statusCode === 401) {
this.errorMessage = '登录已过期,请重新登录';
} else {
this.errorMessage = '网络不给力,请检查网络后重试';
}
} else if (err instanceof BusinessError) {
this.errorMessage = err.message;
} else {
this.errorMessage = '未知错误,请稍后重试';
}
} finally {
this.loading = false;
}
}
build() {
Column() {
if (this.loading) {
Text('加载中...')
} else if (this.userInfo) {
Text('你好,' + this.userInfo.nickname)
} else if (this.errorMessage !== '') {
Text(this.errorMessage)
}
Button('获取用户信息').onClick(() => {
this.fetchUserInfo();
})
}.width('100%').height('100%').justifyContent(FlexAlign.Center)
}
}
注意三个细节。第一,fetchUserInfo 里 loading 的置位和复位分别放在开头与 finally 里,这样无论成功失败,加载态都不会卡住。第二,HttpClient.get<UserInfo> 的泛型参数让返回的 res.data 直接就是 UserInfo 类型,this.userInfo.nickname 在编译期就能检查拼写错误。第三,页面只处理“给用户看什么”,不处理“错误能不能重试”,重试策略完全由 HttpClient 内部决定,页面与网络层互不干涉。
六、进阶:令牌刷新、取消请求与防重复提交
1. 令牌过期只刷新一次
很多应用会在 401 时自动刷新令牌。正确做法是加一个“正在刷新”的标志位:第一次遇到 401 时去刷新令牌并重发请求,刷新期间其他请求先排队等候,刷新失败则全部失败并跳登录。如果不加标志位,三个并发请求同时 401 会触发三次刷新,后两次拿到的旧令牌还可能互相覆盖。
2. 页面退出时取消请求
用户已经离开页面,请求回来再更新 @State 不仅浪费,还可能因为组件已销毁而报错。鸿蒙的 http 实例没有标准取消接口,实用的做法是在页面 aboutToDisappear 里把请求实例 destroy(),同时在回调里先判断页面是否还在,再决定要不要更新界面状态。
3. 按钮防重复提交
提交类接口最怕用户连续点两次按钮。最简单的做法是结合 loading 状态禁用按钮,或者在 HttpClient 外再包一层“同地址同参数的请求去重”:第一次请求未返回时,第二次直接返回同一个 Promise。前者适合表单提交,后者适合列表刷新,两个手段可以同时用。
七、测试与排障:先复现,再改代码
| 现象 | 先检查什么 | 常见原因 |
|---|---|---|
| 请求一直超时 | 超时配置与服务端耗时 | connectTimeout 太小,或服务端接口本身就慢 |
| 间歇性失败 | 重试次数与退避间隔 | 未重试,或重试间隔太短撞上服务端限流 |
| 页面返回后请求报错 | 实例是否销毁 | destroy() 漏写,或回调里更新了已销毁组件的状态 |
| 业务码判断总失败 | 后端约定的成功码 | 后端用 200 表示成功,封装里却按 0 判断 |
编译报错 arkts-no-any-unknown |
catch (e) 的类型 |
e 是 unknown,先 as Error 再读属性 |
调试时建议先打开日志,把每次请求的地址、耗时、状态码与业务码打印出来,再对照上表定位。没有日志的网络问题,只能靠猜,猜十次错九次。
八、总结:一个可以落地的检查清单
- 先定义错误类型,再写请求逻辑,网络错误与业务错误用
instanceof区分。 - 超时用
connectTimeout与readTimeout配置,不要自己写定时器。 - 重试只针对可重试的网络错误,业务错误立即抛出;等待时间用指数退避。
- 每次请求都在
finally里destroy()实例,避免连接泄漏。 - 页面只负责加载态、成功态与错误提示,不碰任何底层请求细节。
- 令牌刷新只做一次,页面退出要取消请求,提交按钮要防重复点击。
把这六条做完,你的鸿蒙应用就拥有了一个真正可复用的网络层:新页面接接口只需要写十行调用代码,新接口上线只需要改一处配置,出问题时先看错误类型就能定位到网络层还是业务层。希望这篇文章能帮你少踩几个坑,也欢迎在评论区分享你自己的封装思路。
- 点赞
- 收藏
- 关注作者
评论(0)