做鸿蒙原生开发只要应用需要和服务端交互就绕不开网络请求这一层。HarmonyOS NEXT 自带的新一代网络库 Rcp解决了老接口在连接复用、上传下载、Cookie 管理上的不少历史遗留问题但直接用 Rcp 写业务代码会非常碎。我在实际项目里做了一套基于 Rcp 的标准化 Request 工具类今天把这套封装的完整思路、关键实现、踩过的坑一次讲清楚。无论是刚接触鸿蒙网络层的开发者还是想把团队网络层规范化的同学这篇都值得收藏。1. 为什么非要用 Rcp 重写网络层选型背后的真实原因很多人刚看到 Rcp 会问一句之前用老接口写得好好的为什么要换这个问题我当初也问过自己。真做一个需要频繁请求、上传下载、带 Cookie 会话的应用时老方案的短板是藏不住的。1.1 和旧版网络接口相比Rcp 到底强在哪HarmonyOS 早期版本提供的网络请求接口以“能发请求、能拿响应”为目标日常 GET、POST 没问题但一旦场景复杂起来开发者就得自己补轮子连接复用要自己管、上传大文件要考虑内存水位、Cookie 要手动存取、多个请求的优先级和取消策略也没有统一入口。Rcp 在这个基础上做了明显的补强我整理了一张能力对比表方便你一眼看懂差异。能力项旧版网络接口RcpHTTP/HTTPS 基础请求支持支持连接池复用较弱多次请求可能重复建连内置连接池有效降低握手开销Cookie 管理需开发者自行拼装和持久化内置 Cookie 管理器可自动携带重定向处理需手动判断 3xx可配置自动跟随上传/下载能力一般得自己拼流对二进制流、文件传输支持更完整拦截器机制无统一钩子支持请求/响应拦截统一加 Header、打日志非常方便线程模型回调相对原始结合 Promise/async 使用心智负担小Rcp 的定位更像是一个“完整网络层”而不是“请求工具”。它把连接管理、会话持久化、协议处理这些底层事情接住了我们上层只需要关心业务语义。1.2 有了 Rcp为什么还要再套一层 Request 工具类Rcp 给了足够强的底层能力但直接拿来写业务会有一个很现实的问题重复代码太多。比如每次请求都要 setUrl、setMethod、setHeader、setBody再处理响应状态码再解析 JSON一套流程写 20 遍之后你会非常想做个统一入口。标准化 Request 工具类的核心价值有三个。第一统一入口业务方只传 url 和参数不用关心请求头怎么拼、超时怎么设置第二统一异常处理网络错误、业务错误、数据解析错误被统一成一套错误模型前端 UI 只需要根据错误码提示用户不需要在 try-catch 里层层判断第三统一扩展点Token 刷新、日志埋点、请求取消都收敛到一个地方维护改一处全部生效。我在设计时给自己的要求是业务代码里不出现任何 Rcp 请求细节只出现“你帮我请求这个地址参数是这些你告诉我结果或者错误”。下面这套实现就是往这个方向走的。2. Rcp 核心知识拆解跑通之前必须搞懂的 6 个类在写工具类之前先把 Rcp 里的核心类搞清楚。类名不复杂但每个类的边界和职责容易混淆。我按一次真实请求的流转顺序来讲。2.1 HttpClient 和 HttpRequest一个管连接一个描述请求HttpClient 是网络客户端管理连接池、Cookie、全局配置它的典型使用方式是先创建实例然后重复使用。HttpRequest 描述“这一次请求要做什么”包括 URL、方法、Header、Body。理解这两个类的关系可以类比成餐厅HttpClient 是后厨和供应链体系不管点单只管稳定出餐HttpRequest 是顾客手里的那张点菜单每一次都不同。所以封装的第一步就是把 HttpClient 设计成单例整个 App 共用一套连接池和 Cookie。如果每个页面都新建 HttpClient连接池就失去了意义SSL 握手和 TCP 连接的复用率会大幅下降。import { rcp } from kit.NetworkKit; // 创建全局唯一的 HttpClient const httpClient: rcp.HttpClient rcp.createHttpClient({ // 可在这里配置全局默认值 });2.2 HttpRequest 的构建方式URL、Method、Header、BodyHttpRequest 的构建分两步先创建 request 对象再往里填信息。高版本 SDK 普遍支持链式 builder 风格我习惯把 set 方法集中调用可读性更好。const request: rcp.HttpRequest rcp.createHttpRequest() .setUrl(https://api.example.com/v1/user/info) .setMethod(rcp.HttpMethod.GET) .setHeader(Content-Type, application/json) .setHeader(Authorization, Bearer xxxxx);注意一点Header 的 key 是大小写不敏感的但同一个 key 重复设置时后设置的值可能会追加到已有值后面不同 SDK 版本行为不完全一致。为了稳定我封装时都会先把 Header 做一次去重合并只保留最终值。2.3 请求体、响应体与结果类型GET 请求通常不需要 BodyPOST/PUT 需要把参数序列化成字符串。Rcp 的 setBody 支持 string、ArrayBuffer、Object 等类型具体看你传的是 JSON 字符串还是二进制流。响应侧有个容易混淆的点响应对象上有 statusCode、header 等属性但真正的响应体内容要通过 getBody() 或 result 属性获取。不要拿整个 response 对象当正文去解析那是很多新手容易踩的坑。const response: rcp.HttpResponse await httpClient.request(request); const statusCode response.statusCode; const result response.getBody(); // 拿到真正的响应体2.4 超时、重定向、Cookie 配置在哪里设置超时配置分散在两个层面。一个是 HttpClient 创建时的全局配置一个是单次请求的局部配置。我的经验是全局配置兜底局部配置处理特殊场景。const client: rcp.HttpClient rcp.createHttpClient({ connectTimeout: 10000, // 连接超时 readTimeout: 15000, // 读超时 followRedirects: true, // 自动跟随重定向 maxConnectionsPerHost: 5, // 单域名最大连接数 });Cookie 相关配置一般在 HttpClient 级别开启后服务端 Set-Cookie 会被自动管理后续请求自动携带。这块如果应用需要登录态非常建议开启。2.5 拦截器统一处理请求和响应拦截器是 Rcp 里非常实用的机制它允许你在请求发出去之前、响应回到业务层之前插入逻辑。我在工具类里主要用它做三件事注入公共 Header、打印请求日志、检测 401 触发 Token 刷新。拦截器不是中间件函数不同版本注册方式略有差异但核心思路一致拿到请求对象可以改拿到响应对象可以判断。我封装时会把拦截器放到工具类内部业务方不需要接触。3. 标准化 Request 工具类的完整设计与实现这一章是全文的重点我会把工具类的完整代码和设计思路逐步展开。你能直接复制到项目里改改就能用也能从中学到“为什么这么设计”。3.1 设计目标先定接口再写实现写任何工具类我建议先定义好对外接口再考虑内部实现。因为接口代表承诺业务方只依赖接口实现是可以替换的。我设计的 Request 工具类对外能力如下。支持 GET、POST、PUT、DELETE 四种常用方法。支持 Object 参数自动序列化为 JSON。支持统一响应模型业务层拿到的是ResultT而不是裸的 HttpResponse。支持统一异常转译网络异常会被转换为错误码。支持请求取消和生命周期解绑。支持自定义 Header 注入和 Token 刷新。export interface RequestOptions { url: string; method?: HttpMethod; params?: object; // 查询参数或请求体 headers?: Recordstring, string; timeout?: number; // 单位毫秒 showLoading?: boolean; // 是否需要全局 Loading retryCount?: number; // 失败重试次数 } export interface ResultT { code: number; // 业务错误码0 表示成功 msg: string; // 错误描述 data: T | null; // 泛型数据 }3.2 单例 Client 与通用请求方法我先创建单例的工具类内部持有全局 HttpClient。getInstance 保证全局只有一份连接池和 Cookie 管理器。import { rcp } from kit.NetworkKit; export class HttpClientService { private static instance: HttpClientService | null null; private client: rcp.HttpClient; private constructor() { this.client rcp.createHttpClient({ connectTimeout: 10000, readTimeout: 15000, followRedirects: true, }); } public static getInstance(): HttpClientService { if (!HttpClientService.instance) { HttpClientService.instance new HttpClientService(); } return HttpClientService.instance; } }通用 request 方法是整个封装的发动机。它负责把 RequestOptions 转换为 Rcp 的 HttpRequest执行请求捕获异常返回统一 Result。public async requestT(options: RequestOptions): PromiseResultT { const request rcp.createHttpRequest() .setUrl(this.buildUrl(options.url, options.params)) .setMethod(options.method || rcp.HttpMethod.GET) .setHeader(Accept, application/json); // 注入公共 Header比如设备信息 const globalHeaders this.getGlobalHeaders(); Object.keys(globalHeaders).forEach(key { request.setHeader(key, globalHeaders[key]); }); // 业务自定义 Header 覆盖全局 Header if (options.headers) { Object.keys(options.headers).forEach(key { request.setHeader(key, options.headers[key]); }); } // POST 等带 Body 的方法自动序列化 if (options.params options.method ! rcp.HttpMethod.GET) { request.setBody(JSON.stringify(options.params)); } let response: rcp.HttpResponse; try { response await this.client.request(request); } catch (error) { return this.transformError(error); } return this.handleResponseT(response); }这里 buildUrl 的逻辑是如果 url 本身带查询参数我就把 params 里的键值对追加到 query string 上否则只做路径拼接。3.3 业务快捷方法GET、POST、PUT、DELETE有了通用 request 方法快捷方法就是薄薄一层糖。调用方写起来非常直观。public getT(url: string, params?: object, headers?: Recordstring, string): PromiseResultT { return this.requestT({ url, method: rcp.HttpMethod.GET, params, headers }); } public postT(url: string, params?: object, headers?: Recordstring, string): PromiseResultT { return this.requestT({ url, method: rcp.HttpMethod.POST, params, headers }); } public putT(url: string, params?: object, headers?: Recordstring, string): PromiseResultT { return this.requestT({ url, method: rcp.HttpMethod.PUT, params, headers }); } public deleteT(url: string, params?: object, headers?: Recordstring, string): PromiseResultT { return this.requestT({ url, method: rcp.HttpMethod.DELETE, params, headers }); }业务方使用时不需要再关心方法名、Content-Type、Body 序列化只传业务参数。比如获取用户信息const res await HttpClientService.getInstance().getUserInfo(/v1/user/info, { id: 10086 }); if (res.code 0) { // 使用 res.data } else { // 统一错误提示 }3.4 统一响应处理怎么解析 datahandleResponse 方法负责做几件事判断状态码、尝试解析 JSON、把解析结果包成 Result。这里有个关键点业务错误码不等于 HTTP 状态码。有些服务端设计是 HTTP 200 但 body 里 code 非 0有些则是 HTTP 4xx/5xx。两种都要兼容。private async handleResponseT(response: rcp.HttpResponse): PromiseResultT { // HTTP 状态码非 2xx直接按网络异常处理 if (response.statusCode 200 || response.statusCode 300) { return { code: response.statusCode, msg: HTTP 请求失败状态码${response.statusCode}, data: null, }; } try { const body response.getBody(); const json JSON.parse(body as string) as ResultT; return json; } catch (error) { return { code: -10000, msg: 响应数据解析失败, data: null, }; } }这里有个经验如果服务端返回的 JSON 结构不确定建议先解析成Recordstring, unknown再用类型守卫逐步提取字段。不要一上来就JSON.parse(body) as ResultT因为运行时类型不安全泛型不会保护你。3.5 Token 自动注入与失效刷新机制登录态几乎是每个 App 的刚需。我在工具类里设计了一个 TokenProvider业务方只需要在内存或持久化存储里维护 token工具类在发送请求前自动注入 Authorization 头。private tokenProvider: () string | null () null; public setTokenProvider(provider: () string | null): void { this.tokenProvider provider; } private getAuthorizationHeader(): string | null { const token this.tokenProvider(); return token ? Bearer ${token} : null; }在 request 方法里如果 Authorization 头为空且 token 存在就自动注入。当服务端返回 401 或特定业务码时工具类内部触发刷新回调刷新完成后自动重放原请求。这个重放机制需要注意防止并发重复刷新我用了一个简单的 Promise 锁来保证同一时间只有一个刷新任务在跑。3.6 超时与重试策略参数怎么算出来的超时值不是拍脑袋定的。我一般按接口的最慢 P95 响应时间乘 1.5 到 2 倍作为读超时。比如用户信息接口 95% 的请求在 400ms 内返回那么读超时设为 10000ms 已经非常宽松如果是文件上传接口连接超时可以短一点比如 5000ms读超时则要拉长到 30000ms 以上因为大文件传输时间不可控。重试也要慎用。我对 GET 请求默认允许重试 1 次对 POST/PUT 默认不重试因为“重放写请求”有可能造成重复下单、重复扣款这类问题。如果真的需要重试写请求建议前端生成一个幂等键放到 Header 里服务端根据幂等键去重。4. 异常处理与状态码归一化把网络错误变成业务能懂的错误网络层是最容易出现“不可控异常”的地方。用户网络差、DNS 解析失败、证书过期、服务端 502每一种错误的报错文案都不一样如果直接抛给 UI用户看到的就是一堆技术黑话。我在工具类里做了错误归一化。4.1 网络层可能抛出的异常分类我把网络异常归纳成四类连接类异常连接超时、服务端拒绝连接、DNS 解析失败。传输类异常读超时、连接被重置、SSL 握手失败。协议类异常HTTP 状态码异常、响应内容不合法。业务类异常服务端返回的业务错误码。export enum AppErrorCode { SUCCESS 0, UNKNOWN -1, TIMEOUT -10001, NETWORK_ERROR -10002, DNS_ERROR -10003, PARSE_ERROR -10004, HTTP_ERROR -10005, SSL_ERROR -10006, CANCELLED -10007, }4.2 transformError 实现在 request 方法的 catch 分支里我根据错误对象的关键字段做判断转换为上面的错误码。不同 SDK 报错字段名不同但通常有code或message我会同时检查。private transformError(error: Error): Resultnever { const message error.message || ; if (message.includes(timeout) || message.includes(timed out)) { return { code: AppErrorCode.TIMEOUT, msg: 请求超时请检查网络后重试, data: null }; } if (message.includes(DNS) || message.includes(resolve)) { return { code: AppErrorCode.DNS_ERROR, msg: 网络无法连接请检查网络设置, data: null }; } if (message.includes(SSL) || message.includes(certificate)) { return { code: AppErrorCode.SSL_ERROR, msg: 证书校验失败可能存在安全风险, data: null }; } if (message.includes(cancel)) { return { code: AppErrorCode.CANCELLED, msg: 请求已取消, data: null }; } return { code: AppErrorCode.NETWORK_ERROR, msg: 网络异常请稍后重试, data: null }; }这里有个容易被忽视的细节错误文案不要直接把 error.message 透传给用户因为里面可能包含内网域名、堆栈信息既不安全也不友好。正确的是错误分类给自己看错误文案给用户看两者分开。4.3 日志与埋点怎么配合我在工具类里加了一个简单的日志钩子默认只输出到控制台线上环境可以挂载埋点函数把错误码、耗时、请求地址上报到服务端。public setLogReporter(reporter: (event: LogEvent) void): void { this.logReporter reporter; } private reportLog(event: LogEvent): void { console.log([HttpClientService] ${event.method} ${event.url} code${event.code} cost${event.cost}ms); this.logReporter?.(event); }日志内容包括请求方法、URL、HTTP 状态码、业务错误码、耗时、是否重试。有了这些数据线上问题排查会轻松很多。4.4 生命周期与请求取消鸿蒙的页面是有生命周期的如果页面销毁时请求还没返回回调再操作 UI 组件就会触发状态异常。我在工具类里维护了一个请求令牌集合页面在 onPageHide 或 aboutToDisappear 时调用 cancelAll 方法取消当前页面的请求。private requestMap new Mapstring, rcp.HttpRequest(); public cancelAll(tag?: string): void { this.requestMap.forEach((req) { // 通过 Rcp 提供的 abort 或 cancel 接口取消请求 }); this.requestMap.clear(); }这个机制不是可选项是做页面跳转频繁的 App 时必须有的。没有取消机制用户快速退出页面后可能有一堆废弃请求在后台占用连接池资源。5. 实测排查高频问题速查表工具类封装完之后我把它丢进真实项目跑了两个月遇到不少问题这里整理成速查表你能省很多排查时间。现象可能原因排查思路请求一直卡住直到超时域名无法解析或代理设置异常确认测试机能否正常访问该域名检查网络权限是否配置返回 JSON 乱码服务端返回 GBK 编码客户端按 UTF-8 解析优先推动服务端统一 UTF-8若无法改需手动按 charset 转码某些手机请求成功另一些失败证书校验差异或 HTTP/HTTPS 混用确认所有请求是否都是 HTTPS检查证书链完整性登录后 Cookie 不携带未在 HttpClient 开启 Cookie 管理检查创建 HttpClient 时的 Cookie 配置项上传大文件内存飙升使用字符串方式传递文件内容改流式上传避免整个文件载入内存401 后 Token 刷新死循环刷新 Token 的接口本身返回 401在刷新接口上绕过 Token 注入和重放逻辑再补充几个实战中的细节。第一个细节是 Header 的Content-Type陷阱。如果 POST 请求体传的是application/json但服务端只接受application/x-www-form-urlencoded会报参数缺失或签名错误。遇到这种情况先在抓包工具里确认实际发出的 Header 和 Body 格式再决定是改客户端还是和服务端对齐。第二个细节是超时时间的合理设置。有些团队把所有接口统一设置 10 秒超时但确实存在需要 20 秒以上的慢接口用户体验反而变成“必定超时”。我建议工具类提供按接口覆盖超时的能力比如上传走 60 秒普通接口走默认值不能让全局配置一棒子打死所有请求。第三个细节是请求取消后的 catch。很多人在页面销毁时取消请求取消动作本身会触发 catch 分支如果 catch 里又弹 Toast 提示“网络异常”用户就会看到一个莫名其妙的提示。所以我在 transformError 里把取消单独识别成 CANCELLED 错误码UI 层对这个错误码直接静默处理。第四个细节是不要在主线程做数据解析。虽然 Rcp 的请求本身是异步的但大型 JSON 的解析仍然可能阻塞 UI 线程。如果接口返回的数据量大建议解析放到单独的任务队列或使用流式解析。数据量小的话影响不大数据量大千万别懒。第五个细节是版本兼容。Rcp 从推出到现在 API 一直在小幅调整比如某些方法名从getResult变成getBody某些配置项从setConnectTimeout变成构造参数。我的建议是工具类内部统一封装这些差异业务层永远面对稳定接口。升级 SDK 时只改工具类一处而不是全局查找替换。最后说一个我自己的习惯工具类不追求大而全只封装高频、通用、重复的场景。像 WebSocket、文件分片上传这种特殊能力不要硬塞进 Request 工具类里单独再建一个小模块去处理职责边界会清晰很多。我在最初版本里想把文件上传也塞进来结果方法参数越来越多后来拆出去之后工具类又回归了清爽。按这套思路走下来网络层会成为整个项目里最稳定、最不用操心的模块。业务方写页面时只需要关心数据怎么展示服务端出问题时有统一错误码兜底线上问题有日志钩子可查升级 SDK 时改动范围可控。我个人在实际操作中最大的体会是封装的本质不是减少代码量而是减少决策点。把网络请求里的各种选择和判断都收敛到一处项目越大收益越明显。