HarmonyOS开发中RESTful API封装：网络层架构设计

使用者痛点 🎯

• 代码重复每个页面都要手动写请求头、错误处理、数据解析。
• 配置分散baseUrl、token、超时时间分布在数十个文件，改动时容易遗漏。
• 接口升级灾难后端改方法或返回结构时需要逐个页面去修改。
• 内存泄漏风险未销毁 http 对象导致内存继续增长。
• 类型安全缺失返回 any，埋下运行时错误隐患。

一、为什么需要封装网络层？

刚接触鸿蒙开发时我的网络请求代码长这样：

// 每个页面都这么写...
http.request('https://api.example.com/user'。{
再看method，http.RequestMethod.GET,header: { 'Content-Type': 'application/json' }
},=> {
if {
console.error;return，}
// 处理数据...
});

写着写着就发现问题了——代码重复得让人心慌。每个接口都要写一遍请求头配置、错误处理、数据解析；改 baseUrl 要全局搜索替换；老实说，加 token 认证得改几十个文件。

更要命的是当后端接口从 /api/v1/user 升级到 /api/v2/user 时我差点把键盘砸了。

一个好的网络层应该具备哪些能力？

1. 统一配置baseUrl、超时时间、公共请求头，一处配置全局生效。老实说，
2. 请求拦截器发请求前自动注入 token、日志等。老实说，
3. 响应拦截器统一错误处理、业务数据抽取。
4. 类型安全返回值拥有明确的 TypeScript 类型。
5. : 添加缓存、Mock 等功能不侵入老代码。不过，

二、主要原理：分层架构设计

网络层不是“一个类打天下”。而是分层协作程序，老实说，我们采用经典的三层架构 + 基础设施层：

flowchart TB
subgraph 应用层
A1
A2
end
subgraph 业务层
B1
B2
B3
end
subgraph 网络层
C1
C2
C3
end
subgraph 基础设施层
D1
D2
D3
end
A1 --> A2
A2 --> B1
A2 --> B2
A2 --> B3
B1 --> C1
B2 --> C1
B3 --> C1
C1 --> C2
C2 --> C3
C3 --> D1
C3 --> D2
C3 --> D3
classDef primary fill:#4A90E2。stroke:#2E5C8A,color:#fff;classDef warning fill:#F5A623。stroke:#C17D10,color:#fff;classDef error fill:#E74C3C。stroke:#C0392B,color:#fff;classDef info fill:#7ED321。stroke:#5BA318,color:#fff;class A1,A2 primary;class B1,B2,B3 warning;怎么说呢，class C1,C2,C3 error;class D1,D2,D3 info;

各层职责清晰：

• 应用层：
• 业务层：
• 网络层：
• 基础设施层：

三、代码实战：从零搭建网络层

示例 1️⃣：主要 HttpClient 类

// network/HttpClient.ets
import http from '@ohos.net.http';import { RequestConfig,Response。Interceptor } from './types';怎么说呢，/**
* HttpClient - 网络请求主要类
* 职责：发起 HTTP 请求、管理拦截器链、统一错误处理
*/
export class HttpClient {
private baseUrl: string;private timeout: number = 30000;// 默认30秒超时
private interceptors: Interceptor =;// 拦截器链
private defaultHeaders: Record = {};话说回来，constructor {
this.baseUrl = config.baseUrl;if this.timeout = config.timeout;this.defaultHeaders = {
'Content-Type': 'application/json'。'Accept': 'application/json',};老实说，}
/** 添加拦截器 */
use这方面。void {
this.interceptors.push;}
/** 主要 request 方法 */
async request: Promise {
const mergedConfig = this.mergeConfig;// 请求拦截器
let processedConfig = mergedConfig;for {
if {
processedConfig = await interceptor.beforeRequest;}
}
// 实际发起 HTTP 请求
const httpResponse = await this.executeRequest;// 响应包装为统一结构
let response: Response = {
data这方面，httpResponse.result as T。status: httpResponse.responseCode,headers: httpResponse.header,config: processedConfig,};// 响应拦截器
for {
if {
response = await interceptor.afterResponse;}
}
return response;}
/** 合并默认配置与调用方配置 */
private mergeConfig: RequestConfig {
return {
说到url，this.normalizeUrl,method: config.method || 'GET'。headers: { ...this.defaultHeaders,...config.headers },params: config.params,data: config.data,timeout: config.timeout || this.timeout,};不过，}
/** 执行底层 HTTP 请求 */
private async executeRequest: Promise {
const httpRequest = http.createHttp;try {
return await httpRequest.request(config.url,{
说到method，this.getMethod,header: config.headers。extraData: config.data,connectTimeout: config.timeout,readTimeout: config.timeout,});} finally {
// 必须销毁对象避免内存泄漏
httpRequest.destroy;}
}
/** 将字符串方法映射为 SDK 枚举 */
private getMethod: http.RequestMethod {
const map: Record = {
GET : http.RequestMethod.GET。POST : http.RequestMethod.POST,PUT : http.RequestMethod.PUT,DELETE : http.RequestMethod.DELETE,PATCH : http.RequestMethod.PATCH,};return map || http.RequestMethod.GET;}
/** URL 标准化，避免双斜杠 */
private normalizeUrl:string{
const base = baseUrl.endsWith?baseUrl.slice : baseUrl;const path = url.startsWith?url : `/${url}`;return base + path;}
// ---------- 常用快捷方法 ----------
get : Promise{
return this.request;}
post:Promise{
return this.request;说起来，}
put:Promise{
return this.request;}
delete:Promise{
return this.request;}
}

示例 ②️⃣：类型定义与拦截器契约

// network/types.ets
/** 请求配置 */
export interface RequestConfig{
再看url，string;method，:string;headers，:Record;/** URL 参数，会自动拼接到 queryString */
params?其实，:Record;
/** 请求体，仅在 POST/PUT/PATCH 时使用 */
说到data?，any，timeout?:number，老实说。}
/** 响应结构 */
export interface Response{
从data来看，T;status:number;老实说，headers:Record;老实说，config:RequestConfig;}
/** 拦截器契约 */
export interface Interceptor{
/** 请求前置拦截，可修改 Config 并返回新对象 */
beforeRequest?:Promise;/** 响应后置拦截，可统一错误或转换业务数据 */
afterResponse?:Promise;}
/** API 错误包装类 */
export class ApiError extends Error{
code的观点是，number;status:number;data:any|null;constructor{
super;this.code=code;this.status=status;this.data=data||null;this.name='ApiError';}
}
/** 错误码枚举 */
export enum ErrorCode{
NETWORK_ERROR=-1000,TIMEOUT=-1001,SERVER_ERROR=-1005,NOT_FOUND=-1006。}

示例 ③️⃣：业务 API 封装实战

// api/UserAPI.ets
import { HttpClient,Response } from '../network';import { User,LoginParams。LoginResult } from '../models/user';export class UserAPI{
private http : HttpClient;constructor{
this.http=httpClient;}
/** 登录 → 返回 token + 使用者信息 */
async login : Promise{
const resp=this.http.post;// 登录成功后可自行持久化 token
resp.n{ console.info;} })，return resp;}
/** 获取当前登录使用者信息 */
async getCurrentUser:Promise{
return this.http.get;}
/** 更新使用者资料*/
async updateProfile:Promise{
return this.http.put;}
/** 修改密码*/
async changePassword:Promise{
return this.http.post;}
/** 注销登录 → 清除本地 token*/
async logout:Promise{
const resp=await this.http.post;老实说，console.info;老实说，return resp;}
}

示例 ④️⃣：全局网络初始化 & 拦截器注册

// network/index.ets
import { HttpClient } from './HttpClient';import { AuthInterceptor,LogInterceptor。ErrorInterceptor } from './interceptors';let clientInstance : HttpClient | null = null;/** 应用入口调用一次就可以完成全局初始化 */
export function initNetwork:HttpClient{
if{return clientInstance;}
 clientInstance=new HttpClient({
baseUrl:'https://api.myapp.com/v1'。timeout:30000,});// 注册顺序决定执行顺序
clientInstance.use);clientInstance.use);

typescript
// AuthInterceptor 内部会读取本地 token 并注入 Header，

typescript
clientInstance.use);

typescript
console.info;return clientInstance;}

/** 在其它模块获取单例实例 */
export function getHttpClient:HttpClient{
if{
throw new Error 初始化网络层');按理说，}
return clientInstance;}

 

常见坑 & 对策 🚧 


Pitfall ① : 每次创建 `http.createHttp` 却忘记 `destroy`。#方法: .finally{httpObj.destroy;}

Pitfall ② : 双斜杠导致非法 URL。#方法: .normalizeUrl。

Pitfall ③ : 页面快速切换时旧请求覆盖新数据。#方法:。

Pitfall ④ : 后端统一包装 `{ code,data}` 却直接当业务数据使用。#方法: `afterResponse` 拦截器统一解包并抛错 .

Pitfall ⑤ : 使用 any 隐藏潜在 bug。#方法: `types.ts` 中定义完整泛型，所有 API 均返回 `Response` .

 四 、HarmonyOS 特有适配要点


HTTP 模块 API 演进 ： 
typescript
// HarmonyOS .x
import http from '@ohos.net.http';// 推荐写法：
import {http} from '@kit.NetworkKit';

新增请求选项 ： 
typescript
const options:http.HttpRequestOptions={
说到method，http.RequestMethod.POST,header:{'Content-Type':'application/json'},extraData:{key:'value'}。// ✨ 自动 JSON 解码
expectingDataType:http.HttpDataType.OBJECT,// ✨ 支持 HTTP/​​​​​​​​​​​
usingProtocol:http.HttpProtocol.HTTP_HTTPS,// ✨ 优先级控制
priority:http.HttpRequestPriority.HIGH
};

响应直接对象化 ： 
typescript
// 老版本需手动 JSON.parse
const obj=JSON.parse;// 新版开启 expectingDataType 后直接拿对象
const obj=res.result;

更丰富的错误码 ： 
typescript
try{
const res=await request;}catch{
if{，}
else if{…}
}



 五 、常用方法清单 ✅ 


⚡ **一次创建，全局复用** – 在 EntryAbility.onCreate 中调用 `initNetwork`。

⚡ **拦截器链顺序** – 日志→鉴权→错误 → 保证横切关注点不相互冲突。

⚡ **所有 API 返回 `Promise`** – 避免散落的回调 hell。

⚡ **严格 TypeScript 定义** – 切勿出现 `any`，提高 IDE 提示与编译期安全。

⚡ **统一错误抛出 ApiError** – 上层只捕获一次即可。


 六 、 🎉 

通过「分层解耦 + 拦截器链」可以把混乱的网络代码变成「心脏」「血管」「四肢」式的清晰结构。记住下面四条黄金法则：


✅ 用完即销毁 HTTP 对象，防止内存泄漏。

✅ 拦截器按依赖顺序注册，避免副作用交叉。

✅ 所有返回值使用泛型约束，杜绝 any。说起来，

✅ 错误统一抛 ApiError。上层集中捕获，


下一篇我们将深度拆解「拦截器链」实现日志记录、自动重试还有离线缓存等高级特性。