鸿蒙应用之网络请求方案总结
一、总体览表
| 方案 | 最低 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 真机必须）
// 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）
import { http } from '@kit.NetworkKit';
✅ 生命周期管理
const req = http.createHttp();
try {const res = await req.request(url, opts);return res.result;
} finally {req.destroy(); // 忘记 destroy 将泄漏 native 句柄
}
✅ HTTP/2 & HTTPDNS 一键开启
http.request(url, {// ...usingHttpdns: true, // 50-100 ms 解析，防劫持usingProtocol: 'HTTP2' // 单连接多路复用，减少 30%+ 延迟
});
3.2 Axios（@ohos/axios）
//axios拦截
axios.interceptors.request.use(config => {config.headers['X-Token'] = AppStorage.Get('token');return config;
});
3.3 WebSocket
✅ 子协议协商
webSocket.connect(url, {header: { 'Sec-WebSocket-Protocol': 'chat' }
});
✅ 自动重连
let reconnect = 0;
ws.on('close', () => {if (reconnect < 3) {setTimeout(() => {reconnect++;ws.connect(url); // 再次握手}, 1000 * reconnect);}
});
3.4 TCP/UDP Socket
import { socket } from '@kit.NetworkKit';
const server = socket.buildTcpServer();
const client = socket.buildTcp();
- 粘包处理：官网提供
DelimiterDecoder工具类，可直接按\n或自定义长度解码，无需手写循环读。
3.5 RCP（该方案目前仅支持Harmony Next ，不支持openHarmony）
特点：
- 接口注解驱动
- 内置连接池、QUIC、GZIP
- 协程写法，杜绝回调地狱
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 需手动解析头 |
五、弱网/无网适配
- 监听网络能力而非单纯“在线/离线”：
netConn.on('netCapabilitiesChange', (cap) => {const isValidated = cap.hasCapability(NetCapabilities.NET_CAPABILITY_VALIDATED);const isWifi = cap.hasTransport(NetTransportType.WIFI);// 按需降级
});
-
预置热点数据
利用 RDB+索引 或 RelationalStore 把首页、个人中心等核心数据做 7 天保质期 持久化，无网时直接读库。 -
图片/视频
开启 HEIF + WebP 自适应，蜂窝网自动降分辨率 50%，代码示例：
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 已内置）
保持依赖最小化、权限声明最简、生命周期最严谨