鸿蒙 ArkTS 网络请求封装与错误处理:从 @ohos.net.http 到可复用的 HttpClient 实战

举报
yd_215301972 发表于 2026/11/19 01:37:06 2026/11/19
【摘要】 前言:为什么每个鸿蒙应用都需要一个网络层刚开始用 ArkTS 写鸿蒙应用时,很多人都是在一个页面里直接写 http.createHttp(),发完请求就 JSON.parse,出错了就弹一个提示。功能跑通之后再看代码,同一个 GET 请求在三个页面里写了三遍,超时时间各不相同,401 要不要跳登录全凭当时的心情,出了问题只能靠猜。等到接口一多、页面一多,这样的代码就成了谁也不敢动的“祖传代...

前言:为什么每个鸿蒙应用都需要一个网络层

刚开始用 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 再读属性

调试时建议先打开日志,把每次请求的地址、耗时、状态码与业务码打印出来,再对照上表定位。没有日志的网络问题,只能靠猜,猜十次错九次。

八、总结:一个可以落地的检查清单

  1. 先定义错误类型,再写请求逻辑,网络错误与业务错误用 instanceof 区分。
  2. 超时用 connectTimeout 与 readTimeout 配置,不要自己写定时器。
  3. 重试只针对可重试的网络错误,业务错误立即抛出;等待时间用指数退避。
  4. 每次请求都在 finally 里 destroy() 实例,避免连接泄漏。
  5. 页面只负责加载态、成功态与错误提示,不碰任何底层请求细节。
  6. 令牌刷新只做一次,页面退出要取消请求,提交按钮要防重复点击。

把这六条做完,你的鸿蒙应用就拥有了一个真正可复用的网络层:新页面接接口只需要写十行调用代码,新接口上线只需要改一处配置,出问题时先看错误类型就能定位到网络层还是业务层。希望这篇文章能帮你少踩几个坑,也欢迎在评论区分享你自己的封装思路。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。