HarmonyOS ArkTS 网络层封装实战：超时、错误分类与并发控制

一、为什么要把网络层单独抽出来

在页面里直接写 http.createHttp()，早期开发很快，但随着接口变多，会出现三类问题：错误处理散落各处、加载态和重试逻辑重复、接口字段变更时改到怀疑人生。把网络请求收敛成独立的数据层，是 HarmonyOS 应用从 Demo 走向工程化的第一步。

二、基础请求的完整写法

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

export interface ApiResult<T> {
  code: number;
  message: string;
  data: T;
}

export async function request<T>(url: string, body: Record<string, Object>): Promise<ApiResult<T>> {
  const httpRequest = http.createHttp();
  try {
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.POST,
      header: { 'Content-Type': 'application/json' },
      extraData: JSON.stringify(body),
      connectTimeout: 10000,
      readTimeout: 15000
    });
    if (response.responseCode !== 200) {
      throw new Error(`HTTP ${response.responseCode}`);
    }
    return JSON.parse(response.result as string) as ApiResult<T>;
  } finally {
    httpRequest.destroy();
  }
}

这段代码有三个容易忽略的细节：

1. 必须 destroy。 每个 http 对象持有底层连接资源，不销毁会造成连接泄漏，长时间运行后出现请求无响应。
2. 显式设置超时。 默认超时较长，弱网环境下页面会长时间停在加载态，用户体验极差。
3. responseCode 不等于业务 code。 200 只代表传输成功，业务是否成功要看返回体里的 code 字段，两者都要校验。

三、统一错误模型

网络层应该把“传输错误、业务错误、解析错误”统一成一种可被 UI 理解的结构，而不是把异常直接抛给页面。

export class ApiError extends Error {
  constructor(
    public kind: 'network' | 'business' | 'parse',
    public code: number,
    message: string
  ) {
    super(message);
  }
}

页面只需要判断 kind：network 提示“网络异常，请重试”，business 展示后端返回的文案，parse 上报监控并提示“数据异常”。这样 UI 的提示逻辑就不会随着接口数量增长而失控。

四、重试与并发控制

不是所有请求都值得重试。GET 类查询可重试 1~2 次，写操作重试要谨慎，避免重复提交。并发控制则针对两种情况：

• 重复点击：提交按钮在请求未返回前应禁用，或对同一接口做请求去重；
• 列表并发：下拉刷新与加载更多同时触发时，用请求序号丢弃过期响应，避免旧数据覆盖新数据。

let seq = 0;

export async function loadPage(page: number): Promise<Item[]> {
  const current = ++seq;
  const result = await request<Item[]>(url, { page });
  if (current !== seq) {
    return []; // 过期响应，直接丢弃
  }
  return result.data;
}

五、鉴权与公共参数

把 token、设备标识、版本号等公共参数放在网络层统一注入，页面不再关心。注意两点：

1. token 失效时统一跳转登录或静默刷新，不要在多个接口里各写一遍判断；
2. 刷新 token 的请求本身不要再触发拦截逻辑，否则会形成死循环。

六、可观测性

线上问题往往依赖日志定位。建议在网络层统一记录：请求路径、耗时、responseCode、业务 code、错误类型。注意不要打印完整请求体和响应体，避免泄露用户隐私与令牌。

七、小结

一个合格的网络层应该做到：请求有超时、资源有释放、错误有分类、并发有控制、鉴权有统一入口、日志可追溯。把这些能力沉到数据层之后，页面代码会变得非常薄，接口调整也只需要改一处。