鸿蒙应用之网络请求方案总结

一、总体览表

方案	最低 API Level	依赖	线程模型	官网状态	备注
@ohos.net.http	8	0 依赖	TaskPool/Worker	Stable	系统内置，支持 HTTP/2、HTTPDNS
@ohos/axios	9	ohpm 1.4.2	Promise	Community	语法同 Web Axios，内部仍封装 http 模块
WebSocket	8	0 依赖	事件派发	Stable	最大 16 KB 单帧，支持子协议
TCP/UDP Socket	8	0 依赖	异步回调	Stable	需自己处理粘包、心跳、加密
RCP (Remote Communication Platform)	10	0 依赖	协程	Stable	鸿蒙官方"Retrofit"，支持接口注解、连接池、QUIC

二、权限配置（HarmonyOS NEXT 真机必须）

json5 复制代码

// module.json5
"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }   // 唯一强制权限
],
"deviceConfig": {
  "default": {
    "network": {
      "cleartextTraffic": true             // 仅当要走 HTTP 明文时需要
    }
  }
}

⚠️ 注意

GET_NETWORK_INFO / SET_NETWORK_INFO 不是网络请求必需，仅在你需要「枚举网卡 / 切换默认网络」时才加。

HarmonyOS NEXT 开始，所有敏感权限 （如位置、相机）都必须动态申请；INTERNET 仍保持 system_grant，声明即生效。

三、方案

3.1 原生 HTTP（@ohos.net.http）

ts 复制代码

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

✅ 生命周期管理

ts 复制代码

const req = http.createHttp();
try {
  const res = await req.request(url, opts);
  return res.result;
} finally {
  req.destroy();          // 忘记 destroy 将泄漏 native 句柄
}

✅ HTTP/2 & HTTPDNS 一键开启

ts 复制代码

http.request(url, {
  // ...
  usingHttpdns: true,     // 50-100 ms 解析，防劫持
  usingProtocol: 'HTTP2'  // 单连接多路复用，减少 30%+ 延迟
});

3.2 Axios（@ohos/axios）

ts 复制代码

//axios拦截
axios.interceptors.request.use(config => {
  config.headers['X-Token'] = AppStorage.Get('token');
  return config;
});

3.3 WebSocket

✅ 子协议协商

ts 复制代码

webSocket.connect(url, {
  header: { 'Sec-WebSocket-Protocol': 'chat' }
});

✅ 自动重连

ts 复制代码

let reconnect = 0;
ws.on('close', () => {
  if (reconnect < 3) {
    setTimeout(() => {
      reconnect++;
      ws.connect(url);   // 再次握手
    }, 1000 * reconnect);
  }
});

3.4 TCP/UDP Socket

ts 复制代码

import { socket } from '@kit.NetworkKit';
const server = socket.buildTcpServer();
const client = socket.buildTcp();

粘包处理：官网提供 DelimiterDecoder 工具类，可直接按 \n 或自定义长度解码，无需手写循环读。

3.5 RCP（该方案目前仅支持Harmony Next ，不支持openHarmony）

特点：

接口注解驱动
内置连接池、QUIC、GZIP
协程写法，杜绝回调地狱

ts 复制代码

interface ApiService {
  @GET('user/{id}')
  getUser(@Path('id') id: number): Promise<User>
}

const api = RCP.create(ApiService, { baseURL: 'https://api.example.com' });
const user = await api.getUser(123);

四、缓存 & 优化

级别	官方 API	备注
内存	`@ohos.util.LruCache`	线程安全，支持自定义淘汰策略
磁盘	`@ohos.data.preferences` + 文件锁	非大文件场景（<1 MB）
网络	`Cache-Control`	仅 RCP / Axios 支持，原生 http 需手动解析头

五、弱网/无网适配

监听网络能力而非单纯"在线/离线"：

ts 复制代码

netConn.on('netCapabilitiesChange', (cap) => {
  const isValidated = cap.hasCapability(NetCapabilities.NET_CAPABILITY_VALIDATED);
  const isWifi = cap.hasTransport(NetTransportType.WIFI);
  // 按需降级
});

预置热点数据

利用 RDB+索引 或 RelationalStore 把首页、个人中心等核心数据做 7 天保质期 持久化，无网时直接读库。
图片/视频

开启 HEIF + WebP 自适应，蜂窝网自动降分辨率 50%，代码示例：

ts 复制代码

Image({ src: url })
  .sourceSize(isCellular ? { width: 180 } : { width: 720 })

六、常见错误速查

错误码	含义	解决
2300001	无网络	检查 `INTERNET` 权限 + 网络能力
2300002	主机不可达	确认 `cleartextTraffic` 或 HTTPS 证书
2300003	超时	调大 `connectTimeout` / 使用 HTTPDNS
2300006	证书校验失败	导入自定义 CA，或在调试阶段允许 `untrustedCA:true`

八、结语 & 快速选型

普通 REST → @ohos/axios（开发快）或 RCP（性能最优）
实时推送 → WebSocket（支持子协议、自动重连）
私有协议 → TCP/UDP Socket（记得用新 API + 粘包解码器）
图片/大文件下载 → 开启 HTTP/2 + 断点续传（RCP 已内置）

保持依赖最小化、权限声明最简、生命周期最严谨