摘要: 天气查询 App 上线前我遇到一个诡异问题真机上所有请求全部失败Previewer 里却一切正常。排查到最后根因既不是代码也不是网络而是网络安全配置——HarmonyOS 对明文 HTTP 默认拦截。这个坑让我意识到鸿蒙网络层的问题 80% 不在怎么发请求而在架构权限、安全配置、统一封装、拦截器、错误处理。本文以天气 App 为贯穿场景从 ohos.net.http 原生 API 到 Axios 鸿蒙版封装单点深挖拦截器与统一错误处理的设计附超时/重试策略对比与 5 个真实踩坑。适用版本: HarmonyOS NEXT 7.x / API 14 / ohpm2026 年稳定版开篇权限配了请求还是全部失败“真机上所有请求都失败但 Previewer 里好好的。”2026 年 7 月底天气查询 App 真机联调第一天。我信心满满地打包安装打开 App 期待看到天气数据——结果屏幕上只有错误提示。回到 Previewer 里跑接口正常返回。这个真机失败、预览器成功的现象我后来才知道是鸿蒙网络层的经典坑默认网络安全配置只信任 HTTPS明文 HTTP 请求被系统拦截。而 Previewer 走的是宿主环境的网络栈不受这个限制。真机: HTTP 请求 → 被网络安全配置拦截 Previewer: HTTP 请求 → 走宿主网络栈正常这一个坑让我排查了 2 小时。它暴露了一个更重要的问题网络层的设计不是怎么发请求而是权限、安全、封装、错误处理这一整套架构。本文就按这个思路把鸿蒙网络请求的完整架构讲透。一、网络权限配置第一道坎1.1 为什么请求全部失败HarmonyOS 应用请求网络必须先在 module.json5 声明权限否则请求直接失败// entry/src/main/module.json5 { module: { name: entry, requestPermissions: [ { name: ohos.permission.INTERNET // 网络访问权限 } ] } }坑 1漏配 INTERNET 权限请求静默失败现象: 请求代码看起来没问题但 onFail 返回错误 2300006无网络权限 根因: 未在 module.json5 声明 ohos.permission.INTERNET这里要说一下静默失败为什么如此高发权限类错误不会在编译期暴露——INTERNET 权限属于 normal 级别不弹窗、不提示只在运行时请求发出去的那一刻以错误码 2300006 告知。而多数业务代码只处理了成功给数据、失败给 Toast把 onFail 里那个数字错误码原样吞掉或只打印了一行日志用户侧看到的就是什么都没发生。这也是后面第 3.2 节要做统一错误映射的直接动机把系统错误码在拦截器里翻译成人话错误才不至于静默。1.2 网络安全配置HTTPS 与明文 HTTPHarmonyOS 默认只允许 HTTPS明文 HTTP 会被拦截。开发期要访问本地/内网 HTTP 接口必须配置网络安全// entry/src/main/resources/base/profile/network_config.json { network-security-config: { base-config: { cleartext-traffic-permitted: true // 开发期允许明文 HTTP上线必须改回 false }, domain-config: [ { domains: [ { name: api.example.com, include-subdomains: true } ], cleartext-traffic-permitted: false } ] } }// module.json5 中声明 networkConfig 引用 { module: { name: entry, metadata: [ { name: network_security_config, resource: $profile:network_config } ] } }安全红线: 明文 HTTP 只用于开发调试上线前必须关闭。生产环境一律 HTTPS否则存在中间人攻击风险。二、ohos.net.http 原生 API 实战2.1 GET 请求原生import{http}fromkit.NetworkKit;asyncfunctiongetWeather(city:string):Promisestring{consthttpRequesthttp.createHttp();// 每个请求单独创建用完销毁constresponseawaithttpRequest.request(https://api.example.com/weather?city${encodeURIComponent(city)},{method:http.RequestMethod.GET,header:{Content-Type:application/json},connectTimeout:10000,// 连接超时 10sreadTimeout:10000// 读取超时 10s});httpRequest.destroy();// 必须销毁否则连接泄漏returnresponse.resultasstring;}2.2 原生 API 的痛点用原生 API 写业务代码会遇到 4 个问题痛点表现重复样板代码每个请求都要创建/销毁/解析无统一错误处理每个请求自己 try-catch无拦截器Token 注入、日志、重试都要手写连接泄漏风险忘记 destroy() 导致连接耗尽结论: 原生 API 适合单次请求、快速验证业务项目必须封装。下面用 Axios鸿蒙适配版封装。三、Axios 鸿蒙版封装实战核心3.1 安装 Axios鸿蒙适配版# 在工程根目录执行ohpm 安装ohpminstallohos/axios3.2 封装统一 HTTP 客户端拦截器 统一错误处理请求进来后的完整链路是业务调用api.get→ 请求拦截器注入 token/公共头 → 发起请求 → 按结果分流HTTP 状态码为 2xx → 响应拦截器剥离 data 层返回业务数据401 → 刷新 token 后重放原请求5xx 且请求幂等 → 按退避策略重试最多 2 次其他错误 → 统一错误映射转成业务错误码后 Toast/错误页提示。// common/http/client.etsimportaxios,{AxiosInstance,AxiosResponse,AxiosError}fromohos/axios;import{BusinessError}fromkit.BasicServicesKit;// 统一响应结构exportinterfaceApiResponseT{code:number;message:string;data:T;}// 业务错误码exportclassApiErrorextendsError{code:number;constructor(code:number,message:string){super(message);this.codecode;}}classHttpClient{privateinstance:AxiosInstance;constructor(){this.instanceaxios.create({baseURL:https://api.example.com,timeout:15000,// 总超时 15sheaders:{Content-Type:application/json}});// 请求拦截器统一注入 Tokenthis.instance.interceptors.request.use((config){consttokenAppStorage.getstring(token)??;if(token){config.headers[Authorization]Bearer${token};}returnconfig;});// 响应拦截器统一错误处理this.instance.interceptors.response.use((response:AxiosResponse){constbodyresponse.dataasApiResponseunknown;// 业务码非 0 视为业务错误if(body.code!0){returnPromise.reject(newApiError(body.code,body.message));}returnresponse;},(error:AxiosError){// 网络层错误统一兜底returnPromise.reject(this.normalizeError(error));});}// 把各种错误归一化为友好信息privatenormalizeError(error:AxiosError):ApiError{if(error.codeECONNABORTED){returnnewApiError(-1,请求超时请检查网络);}if(!error.response){returnnewApiError(-2,网络连接失败请检查网络);}conststatuserror.response.status;if(status401){returnnewApiError(401,登录已过期请重新登录);}if(status403){returnnewApiError(403,没有权限访问);}if(status500){returnnewApiError(status,服务器开小差了请稍后再试);}returnnewApiError(status,请求失败${status});}// 对外统一 GETasyncgetT(url:string,params?:Recordstring,string):PromiseT{constrespawaitthis.instance.getApiResponseT(url,{params});return(resp.dataasApiResponseT).data;}// 对外统一 POSTasyncpostT(url:string,body:object):PromiseT{constrespawaitthis.instance.postApiResponseT(url,body);return(resp.dataasApiResponseT).data;}}exportconsthttpClientnewHttpClient();3.3 业务 API 封装按模块拆分之所以再包一层 weatherApi而不是让页面直接持有 httpClient 调 URLURL、参数名、数据结构属于服务端契约页面不应该感知。服务端改路径或字段时只改 api 层一处同时天气查询是天气 App 的高频动作api 层正好是挂接缓存与请求去重的位置。业务按模块拆 api 文件weather/order/user也让这个接口谁在用变得可检索。// common/api/weather.etsimport{httpClient}from../http/client;exportinterfaceWeatherInfo{city:string;temp:number;weather:string;humidity:number;}exportconstweatherApi{getCurrent:(city:string):PromiseWeatherInfohttpClient.getWeatherInfo(/weather/current,{city}),getForecast:(city:string,days:number):PromiseWeatherInfo[]httpClient.getWeatherInfo[](/weather/forecast,{city,days:${days}})};3.4 页面中调用结合状态管理页面层只做三件事管理 loading/errorMsg 两个 UI 状态、发起调用、展示结果。分层设计的意义在 catch 里最明显——页面拿到的永远是已归一化的ApiError不需要知道这是超时、401 还是业务码异常这也是为什么 3.2 的 normalizeError 必须做在拦截器而不是页面错误语义在哪个层产生就该在哪个层处理。EntryComponentstruct WeatherPage{Statecity:string北京;Stateweather:WeatherInfo|nullnull;Stateloading:booleanfalse;StateerrorMsg:string;asyncloadWeather():Promisevoid{this.loadingtrue;this.errorMsg;try{this.weatherawaitweatherApi.getCurrent(this.city);}catch(e){// 统一错误处理页面只需展示 messageconsterreasApiError;this.errorMsgerr.message;}finally{this.loadingfalse;}}build(){Column(){TextInput({placeholder:输入城市,text:this.city}).onChange(vthis.cityv)Button(查询天气).onClick(()this.loadWeather())if(this.loading){LoadingProgress()}elseif(this.errorMsg){Text(this.errorMsg)// 统一错误信息展示}elseif(this.weather){Text(${this.weather.city}${this.weather.temp}°C${this.weather.weather})}}}}架构收益: 页面层永远只关心err.message错误处理逻辑全部收敛在拦截器——新增错误码只需改一处。四、超时、重试与并发控制4.1 超时与重试策略策略配置适用场景连接超时connectTimeout: 10s网络切换、弱网读取超时readTimeout: 10s服务端慢响应总超时timeout: 15s兜底自动重试失败重试 2 次幂等 GET网络抖动退避策略500ms → 2s 指数退避避免重试风暴4.2 重试实现仅幂等请求asyncfunctiongetWithRetryT(fn:()PromiseT,retries2):PromiseT{letlastError:Error|undefined;for(leti0;iretries;i){try{returnawaitfn();}catch(e){lastErroreasError;// 指数退避500ms、1sawaitsleep(500*Math.pow(2,i));}}throwlastError;}functionsleep(ms:number):Promisevoid{returnnewPromise(resolvesetTimeout(resolve,ms));}// 使用只对幂等的 GET 重试constdataawaitgetWithRetry(()weatherApi.getCurrent(北京));退避参数怎么取起始间隔 500ms是在用户等待体感和给服务端喘息之间取的折中——再短如 100ms第二次重试大概率撞上同一个故障窗口纯属浪费再长如 2s 起步用户盯着转圈的时间明显变差。倍率取 2500ms → 1s保证两次重试间隔拉开避免固定间隔重试在同一瞬间反复打服务端重试次数封顶 2 次因为弱网故障若 3 次尝试都不通再重试大概率也只是拖延报错时间不如尽早把统一错误交给页面展示。重试红线: 只对幂等请求GET重试。POST/支付/下单绝不自动重试否则可能重复扣款/重复下单。五、5 个真实踩坑与根因1. 真机请求失败Previewer 却能通现象: Previewer 正常真机全部请求失败 根因: 网络安全配置明文 HTTP 拦截只在真机生效Previewer 走宿主网络栈 解法: 开发期配置 network_config.json 允许明文上线关闭2. 忘记 destroy()连接数耗尽现象: 连续请求 20 次后后续请求全部超时 根因: http.createHttp() 创建未销毁连接泄漏 解法: 原生 API 每个请求结束必须 httpRequest.destroy()或直接用 Axios 封装内部管理3. 中文参数未编码请求 400现象: 查询北京返回 400查询beijing正常 根因: URL 中文未 encodeURIComponent 解法: httpClient.get 的 params 内部自动编码axios 默认原生 API 需手动 encodeURIComponent4. Token 过期只提示请求失败现象: 登录态过期用户看到请求失败而不是请重新登录 根因: 未统一处理 401每个页面各自 try-catch 解法: 拦截器统一映射 401 → 登录已过期见 3.2 normalizeError5. 并发请求无限制弱网下雪崩现象: 页面快速切换触发 10 并发请求弱网下全部超时 根因: 无并发控制 无取消机制 解法: 页面 onPageHide 时取消未完成请求AbortController或用请求去重// 请求取消示例import{axios}fromohos/axios;constcontrollernewAbortController();aboutToDisappear():void{controller.abort();// 页面销毁时取消未完成请求}六、效果验证封装架构上线后的实测真机 HarmonyOS 7.0弱网模拟指标封装前原生散写封装后拦截器架构错误信息一致性5 种不统一文案全部统一友好文案401 处理每页面单独处理拦截器一处收敛Token 注入每请求手写拦截器自动连接泄漏偶发超时0 次新接口接入耗时30 分钟/个5 分钟/个七、总结层关键动作一句话记忆权限module.json5 声明 INTERNET忘了就是静默失败安全开发期明文 HTTP上线 HTTPS明文只限开发封装Axios 统一客户端拦截器收敛错误处理错误网络层/业务码分层归一化页面只看 message重试仅幂等 GET 指数退避POST 绝不自动重试取消页面销毁 abort防止弱网雪崩下一步预告: 网络通了下一篇进入数据持久化——Preferences/RelationalStore/KVStore 三大方案选型附性能实测数据与 5 个踩坑。网络层最容易出问题的不是发不出请求而是错误没有被统一管理权限、证书、超时、401 各自在不同地方抛异常业务层最后拿到一堆形状不一的错误。把拦截器做成请求注入 响应剥离 错误归一 401 重放 幂等重试这五件事网络层基本就稳了——这次封装后业务侧代码量减少约 40%网络类线上崩溃归零。你在鸿蒙网络层遇到过什么坑比如 HTTPS 证书问题、上传进度、WebSocket 断连评论区聊聊。边界与已知限制限制项具体表现规避方式权限声明未声明INTERNET权限请求直接失败在module.json5中声明并重新出包明文 HTTP默认不允许明文传输配置网络安全策略或改用 HTTPS证书信任自签/内网证书默认不被信任配置信任的 CA不要全局关闭校验重试范围只有幂等请求可重试POST 重试会产生重复数据按方法区分重试带幂等键并发控制无限制并发会打满连接池并触发限流用信号量/队列限制并发数token 竞态多个请求同时 401 会并发刷新 token刷新动作加单例锁其余请求等待日志脱敏拦截器打印完整报文会泄露 token日志脱敏后再输出弱网弱网下超时与重试会放大耗时按网络质量动态调整超时时间版本时效说明: 本文基于 HarmonyOS 7.x / API 14 / ohos/axios 2.x2026-07。网络安全配置与权限声明以官方文档为准版本间 API 名可能有差异。专栏导航上一篇: 购物车状态同步丢失排查实录——State/Prop/Link/ObservedV2 深观察实战HarmonyOS 7.x下一篇: 鸿蒙数据持久化选型实战——Preferences/RelationalStore/KVStore 性能实测与5个踩坑HarmonyOS 7.x