★ FEATURED ARTICLE 作为一名在跨端开发一线摸爬滚打多年的工程师我第一次把 React Native 应用跑在 OpenHarmony 设备上时心里其实并没有太多底气。鸿蒙生态的 ArkUI 渲染引擎跟原生 RN 的桥接逻辑差异很大光是环境适配就折腾了两三天。真正让我决定写这篇分享的是后面在封装网络层时踩到的一个连环坑——axios请求拦截器在鸿蒙侧的行为和 Android/iOS 上并不完全一致如果不做针对性处理线上应用分分钟会出事故。这篇内容适合谁看呢两种情况一是你正打算把现有的 React Native 工程迁移到 OpenHarmony 设备上二是你已经在鸿蒙设备上跑 RN但网络请求层还是一片混乱想系统性地把拦截器、统一错误处理、Token 续期这些基建搭起来。我会把自己实测过的完整链路拆开讲包括环境适配、拦截器设计、OpenHarmony 特有的坑和调试手法尽量做到你照着操作就能复现。1. 为什么在 OpenHarmony 的 RN 工程里网络层必须做拦截器封装先说一个现象。很多人写 React Native 的网络请求习惯用fetch一把梭用到哪个页面就在哪个页面发请求、处理返回值。这种方式放在 Android 和 iOS 上勉强能跑但移植到 OpenHarmony 设备上你很快会发现三个痛点Token 过期后的统一跳转没法收敛、请求日志难以排查、错误提示每个页面写一份还各不相同。拦截器解决的就是横切关注点。我举几个实际场景用户登录后每个接口都要在请求头里带Authorization: Bearer xxx如果每个页面手动加漏一个接口就会 401Token 过期时理论上应该静默刷新 Token 然后重放原请求这个逻辑如果散落在业务代码里基本没法维护鸿蒙设备端的长连接和弱网环境比手机更复杂接口 504 或超时时需要统一的提示文案和降级策略。Axios 的interceptors.request和interceptors.response恰好能把这类逻辑收敛到一个文件里。在标准 React Native 工程里这么做已经很成熟了但到了 OpenHarmony 上因为网络栈、事件循环、异步任务调度的实现差异拦截器里的很多细节必须重新验证。我这里不是建议你把所有业务逻辑都塞进拦截器。拦截器适合做的是统一的请求头处理、统一的错误分类、统一的鉴权逻辑。至于具体页面是弹 toast 还是跳详情页那属于业务层不该放在拦截器里。2. 环境适配在 OpenHarmony 上给 RN 工程装好 axios 底座在讲拦截器代码之前得先把环境说清楚。OpenHarmony 上跑 React Native目前主流方案是通过 OpenHarmony 官方适配套件把 RN 桥接到 ArkUI 侧。这套适配层负责把 RN 的网络请求、原生模块、事件回调都转换到鸿蒙的通信机制上。2.1 工程初始化与依赖版本对齐我当时用的是开源社区的 RN 鸿蒙化工程模板初始化完成后Node 依赖里需要同时有{ react-native: 0.72.x, react-native-community/cli: 12.x, axios: ^1.6.0, ohos/react-native: 对应的鸿蒙适配版本 }这里有个容易被忽略的点axios 的版本不能一味追新。在鸿蒙适配层的 HTTP 通信链路上部分新版 axios 在FormData处理、Blob响应解析上存在兼容性差异。我实测下来 1.6.x 是最稳的1.7 以上在某些大文件流式上传场景会偶发中断。安装命令不复杂npm install axios^1.6.0但要特别注意鸿蒙侧原生工程里需要配置网络权限。在module.json5的requestPermissions里加入{ name: ohos.permission.INTERNET }很多人装完包直接跑发现请求发出去没反应、报错信息又是空的九成是权限没配。2.2 为什么建议把 HTTP 客户端独立成模块在开始写拦截器之前先做一个单例封装。我喜欢把 axios 实例单独放一个文件这样可以保证整个应用只维护一套拦截器配置而不是每个页面各自axios.create一次。// http.ts import axios, { AxiosInstance, AxiosRequestConfig } from axios; const instance: AxiosInstance axios.create({ baseURL: https://api.example.com, timeout: 15000, headers: { Content-Type: application/json, }, }); export default instance;注意 baseURL 在鸿蒙侧有个细节——如果你线上接口域名是 HTTPS 但证书链包含多个中间证书Axios 适配层默认校验策略可能会导致某些设备握手失败。我在后面调试环节会专门说这个。3. 请求拦截器统一鉴权、签名和请求头注入请求拦截器的作用时机是在请求正式发出之前。你可以在这里修改请求配置、追加 header、设置加密签名甚至可以中断请求。3.1 携带 Token 的完整实现先看一个最基本的实现// 引入上面创建的 instance import instance from ./http; import { getToken, getDeviceInfo } from ./storage; instance.interceptors.request.use( async (config) { // 从本地存储读取 token const token await getToken(); if (token) { config.headers.Authorization Bearer ${token}; } // 一些业务上要求的基础参数 config.headers[x-platform] openharmony; config.headers[x-device-id] await getDeviceInfo(); return config; }, (error) { return Promise.reject(error); } );这里有两个 OpenHarmony 上的注意点第一getToken建议从异步存储中读取。鸿蒙侧的 AsyncStorage 实现和原生 RN 有差异如果你在请求拦截器里用同步读取的 localStorage 方案高并发场景下会偶发读取到空值。我当时的解决方案是维护一个内存缓存启动时从磁盘预读 Token 到内存拦截器同步取内存值这样既快又稳。第二如果你有设备指纹或风控参数最好做个防抖处理不要每次都重新计算。鸿蒙设备上的某些指纹算法在计算时会涉及硬件接口调用耗时有几十毫秒放到拦截器里会导致每个请求慢几十毫秒性能损耗非常明显。3.2 参数签名与请求体处理细节除了 Token还有一类拦截器场景是签名。假设你的后端要求每个请求都带有基于 timeStamp、nonce 和 body 的签名请求拦截器就需要在发送前对数据进行一次规整。instance.interceptors.request.use( async (config) { const timestamp Date.now(); const nonce Math.random().toString(36).slice(2); let signStr timestamp nonce; if (config.data) { // 如果请求体是 JSON 对象需要序列化后参与签名 const bodyStr JSON.stringify(config.data); signStr bodyStr; } // signStr 加盐后做 hash具体算法按后端约定 const sign await hashWithSalt(signStr); config.headers.timestamp String(timestamp); config.headers.nonce nonce; config.headers.sign sign; return config; }, (error) Promise.reject(error) );这里有个经验参与签名的数据必须是服务端实际收到的最终数据。如果你在拦截器里改了config.data但没有同步修改参与签名的字符串后端验签会直接失败。我一开始踩过这个坑最后统一原则是先在拦截器里完成参数格式化格式化之后的结果作为唯一签名源。3.3 请求中断与会话恢复还有一个很少人提到的场景在 OpenHarmony 的鸿蒙设备上应用可能因为系统资源紧张被冻结用户切回前台时之前挂起的请求会一次性涌出。如果这些请求携带的还是旧 Token可能会集体 401。我建议在请求拦截器里增加一个“会话状态检查”import { sessionState } from ./session; instance.interceptors.request.use(async (config) { // 如果是非公开接口且会话已失效直接抛出业务错误 if (!config.public !sessionState.isValid()) { const err new Error(SESSION_EXPIRED); err.name BizError; return Promise.reject(err); } // 否则正常注入 token return config; });这样可以把无效请求提前掐断避免一批请求同时打到后端触发雪崩。尤其鸿蒙设备内存有限这种保护能做还是做一下。4. 响应拦截器统一错误分类、Token 静默续期与重试响应拦截器才是真正体现工程能力的地方。请求拦截器只是把请求头收拾利索响应拦截器要面对的是各种乱七八糟的后端返回——业务错误码、HTTP 异常、超时、离线、数据格式不对、沙箱策略作祟。4.1 按 HTTP 状态和业务码双层分流一般的后端返回结构长这样{ code: 200, message: success, data: {} }HTTP 状态码可能永远是 200业务是否成功看code字段。这个时候响应拦截器就要先判断 HTTP 状态再判断业务码instance.interceptors.response.use( (response) { const res response.data; // 如果接口本身是文件流直接透传 if (response.config.responseType blob) { return res; } if (res.code ! 0) { // 业务错误统一转成自定义错误对象 const bizError new Error(res.message || 业务处理失败); bizError.name BizError; bizError.code res.code; return Promise.reject(bizError); } return res.data; }, (error) { // 网络层错误在这里处理 return handleNetworkError(error); } );为什么要统一转成BizError因为在业务页面里你只需要 import 一个错误判断工具if (error.name BizError) { // 显示后端返回的 message }而不需要一层层解构 response。这个习惯在任何平台都适用在 OpenHarmony 上尤其重要因为鸿蒙侧错误对象在不同模块间传递时proprtype 的保留行为跟其他平台不完全一致提前统一结构可以少踩很多坑。4.2 Token 过期时的静默续期与请求重放这是整个拦截器封装里最复杂的部分也是很多团队在 OpenHarmony 上不敢做拦截器的原因。我给出一个经过多端验证的完整方案核心逻辑是当响应拦截器捕获到 401 时先判断是否已经在刷新 Token如果是则把请求挂到队列里等新 Token 返回后再重放如果否则立即发起刷新请求。let isRefreshing false; let queue: Array(token: string) void []; async function handleUnauthorized(error: any) { const originalRequest error.config; if (!originalRequest._retry) { originalRequest._retry true; if (!isRefreshing) { isRefreshing true; try { const newToken await fetchRefreshToken(); // 更新本地存储的 token await saveToken(newToken); // 唤醒所有挂起的请求 queue.forEach((resolve) resolve(newToken)); queue []; return instance(originalRequest); } catch (refreshError) { // 刷新失败清空队列并跳登录 queue []; redirectToLogin(); return Promise.reject(refreshError); } finally { isRefreshing false; } } // 正在刷新 Token把当前请求挂起 return new Promise((resolve, reject) { queue.push((newToken) { originalRequest.headers.Authorization Bearer ${newToken}; resolve(instance(originalRequest)); }); }); } return Promise.reject(error); }这里有一个关键细节刷新 Token 的请求本身不能走业务拦截器。我实现时单独创建一个裸 axios 实例来发 refresh 请求避免它递归调用handleUnauthorized导致死循环。另外注意originalRequest._retry这个自定义字段在 OpenHarmony 适配层下是可以正常透传的但如果你用的 axios 版本太老需要看一下AxiosRequestConfig的索引签名是否允许额外字段。1.6.x 没问题。4.3 网络错误处理与鸿蒙弱网特点OpenHarmony 设备很多是 IoT、平板、电视这类形态网络环境比手机差得多。响应拦截器的错误处理器我建议至少区分四类错误类型判断依据处理建议超时error.code ECONNABORTEDtoast 提示“网络超时”可附带重试按钮网络不可用error.message.includes(Network Error)或error.code ERR_NETWORK引导检查网络连接401error.response.status 401走 Token 续期流程5xxerror.response.status 500后端服务异常提示稍后再试在 OpenHarmony 上timeout触发的错误对象里message有时是中文的比如出现“网络连接失败”“请求超时”。我做判断时优先看error.code而不是message这样兼容性最好。还有个很隐蔽的坑如果 TV 盒子长时间休眠后唤醒网络栈可能处于半初始化状态第一次请求会失败但第二次就好了。针对这种情况我在处理器里加入了“单次自动重试”策略if (error.code ERR_NETWORK !error.config?._isRetryNetwork) { error.config._isRetryNetwork true; return instance(error.config); }实测对提高鸿蒙设备弱网下的请求成功率帮助非常大。5. 拦截器之外的细节BaseURL、证书校验、日志与调试拦截器本身写完了不代表网络层就稳了。OpenHarmony 上还有几个跟拦截器强相关的周边问题必须一起说。5.1 BaseURL 与多环境切换在鸿蒙设备上调试时二维码扫码安装的 App 怎么切换测试环境我建议不要写成通过 UI 手动输入地址而是利用打包时的环境变量注入。拦截器里读取的baseURL不要写死用宏定义或app.config注入。import { AppConfig } from ./appConfig; const instance axios.create({ baseURL: AppConfig.apiBaseUrl, });AppConfig在鸿蒙侧的构建脚本里根据 debug/release 区分。这样可以避免误把测试地址发布上线。5.2 证书链路问题与 HTTPS 抓包调试阶段需要抓包看拦截器前后的数据但鸿蒙设备的证书信任机制和 Android 不太一样。默认情况下系统 CA 证书是不包含 Charles 或 Fiddler 的根证书的需要把抓包工具的证书导入到系统信任区这个操作在鸿蒙开发版上支持量产机上就别想了。这里提供一个思路用鸿蒙侧的日志输出代替抓包。在拦截器里加一个 debug 模式的请求日志中间件const logMiddleware (config: any) { if (__DEV__) { console.log([HTTP ${config.method?.toUpperCase()}] ${config.url}); console.log(Headers:, JSON.stringify(config.headers)); console.log(Body:, JSON.stringify(config.data)); } return config; }; instance.interceptors.request.use(logMiddleware);响应端也打印状态码和耗时这样在 DevEco Studio 的日志面板里就能完整还原每次请求的链路。5.3 并发请求导致 Token 刷新风暴最后再说一个生产环境容易炸的点。假设应用启动时有 10 个请求同时发出这 10 个请求全部在刷新 Token 前就收到了 401如果没有做上面提到的队列挂起机制就会产生 10 个刷新 Token 请求并行发出。这个问题的根源是刷新 Token 是全局单例操作绝对不能并发执行。我写的isRefreshing标志位就是解决这个问题的。但要注意isRefreshing只能在同一进程内存里有效如果鸿蒙侧上层的 WebView 或者多进程场景各自维护一份 axios 实例就没有办法共享刷新状态了。遇到过这种情况的团队建议把刷新中的状态提升到存储层用信号量或者简单的全局变量跨实例同步。5.4 拦截器不能做的事虽然拦截器很强大但在 OpenHarmony 上我强烈不建议用它做这三件事业务埋点上报。拦截器是网络层公共逻辑埋点数据往往关联具体业务属性放在一起会让拦截器越来越重后续需求迭代时互相牵连。大图/文件上传的分片逻辑。这类逻辑最好独立封装不要跟业务请求混在一套拦截器里否则一旦上传流程出错排查难度翻倍。非 HTTP 的自定义协议请求。RN 工程在鸿蒙上偶尔会走ohos://或本地 socket 通信这些不属于 axios 管辖范围。6. 我在实测中踩过的一些坑按频率排序这部分是我最想写的。拦截器的代码逻辑本身不复杂真正磨人的是那些只有 OpenHarmony 平台才会触发的问题。6.1 AsyncStorage 读取竞态在一次冷启动测试中我发现应用刚启动时立刻发起登录请求Token 偶尔会丢失。排查到最后是 AsyncStorage 在鸿蒙适配层首次读取时和 JS 侧启动任务存在竞态。解决方案很粗暴——把 Token 缓存在内存单例里启动时先异步加载到内存后续读取直接在内存完成。let cachedToken: string | null null; let tokenLoadingPromise: Promisestring | null | null null; export function loadTokenToCache() { tokenLoadingPromise getTokenFromStorage().then((token) { cachedToken token; return token; }); } export function getCachedToken() { return cachedToken ?? tokenLoadingPromise; }拦截器里同步取cachedToken如果为空则 await 那个 Promise。这样既避免每次读取存储的耗时又解决了冷启动竞态。6.2 拦截器内console.log导致性能劣化RN 在鸿蒙上的日志桥接效率不如原生侧如果拦截器里在__DEV__模式下还打印完整的响应体稍微大一点的响应就能把 UI 线程卡好几秒。我的建议是只打印 URL、状态码、耗时和首 200 字符不要整包打。6.3 Headers 里的小写 key 问题axios 在部分鸿蒙适配版本里会把 request headers 转成首字母大写形式但后端可能只能识别小写。如果你发现某些 header 在后端读不到可以先在拦截器里统一把关键 header 用小写赋值并在发送前打印出来确认。6.4 响应拦截器里修改response.config失效有个场景请求失败后我试图在拦截器里修改error.config.headers然后重新请求结果发现修改不生效。检查后确认不是拦截器逻辑问题而是鸿蒙适配层对请求配置对象做了浅拷贝冻结你需要像上面代码里那样传originalRequest._retry标记并重新调用instance(originalRequest)重新走一遍。我在后续项目里把这套拦截器封装沉淀成了一个内部独立模块三个端Android、iOS、OpenHarmony共用同一套逻辑鸿蒙侧只额外处理了环境差异。整个网络层的改动量比预期小很多关键在于把逻辑收敛得足够干净。如果你也在做类似的跨端适配我建议先把自己的拦截器需求列成清单需要注入什么、需要拦截什么错误、需要怎样的重试策略然后再动工。在主线上走得稳后面碰到鸿蒙特有的坑时你才有余力去逐个解决。
阅读完成 · 觉得有帮助？
