鸿蒙网络请求组件库 lib_network 架构设计与实践

一、项目概述

lib_network 是一个基于 @ohos/axios 封装的鸿蒙（HarmonyOS）网络请求组件库，采用分层架构 + 策略模式设计，提供高度可扩展的网络请求能力。该组件库已发布为 HAR（Harmony Ability Resource）包，支持跨模块复用。

1.1 项目结构

tcnetworkproject/
├── AppScope/                    # 应用全局配置
├── entry/                       # 主应用模块
│   ├── src/main/ets/
│   │   ├── apis/                # 业务API定义
│   │   ├── gateway/             # 应用网关实现
│   │   └── pages/               # UI页面
│   └── ohosTest/                # 测试模块
├── lib_network/                 # 网络请求组件库（HAR）
│   ├── src/main/ets/components/
│   │   ├── constants/           # 常量定义
│   │   ├── event/               # 事件对象
│   │   ├── http/                # HTTP核心封装
│   │   ├── model/               # 数据模型
│   │   ├── protocol/            # 协议接口
│   │   └── utils/               # 工具类
│   └── Index.ets                # 模块导出入口
└── libs/                        # 已构建的HAR包

---

二、架构设计亮点

2.1 整体架构图

2.2 核心设计模式

1. 策略模式（Strategy Pattern）

设计意图：将网关协议封装为独立策略，支持运行时切换。

// 网关协议接口 - 策略接口
export abstract class TCServiceProtocol {
  abstract serviceUrl(): string
  abstract requestWithParams(params: Map<string, CommonType>, methodName: string, requestType: RequestType): Map<string, CommonType>
  abstract resultWithResponseObject(originResponse: ApiResponse): string
}

应用场景：不同业务场景可实现不同网关策略，如测试环境、生产环境、加密网关、明文网关等。

2. 模板方法模式（Template Method Pattern）

设计意图：定义请求流程骨架，子类实现具体步骤。

// 请求管理器 - 模板方法
export abstract class TCAPIBaseManager {
  public async loadData(): Promise<string> {
    // 1. 参数校验（钩子方法）
    let booleanParams = await this.paramsListener?.isCorrectWithParamsData(params)
    
    // 2. 请求参数加工（策略方法）
    let paramsEntryMap = await this.tcServiceProtocol.requestWithParams(params, methodName, requestType)
    
    // 3. 请求前拦截（钩子方法）
    this.interceptorListener?.beforeRequestWithParams(params)
    
    // 4. 发起HTTP请求（核心步骤）
    requestPromise = axiosClient.get<ApiResponse>({...})
    
    // 5. 响应后拦截（钩子方法）
    this.interceptorListener?.didReceiveResponse(data)
    
    // 6. 响应解析（策略方法）
    let responseText = this.tcServiceProtocol?.resultWithResponseObject(data)
  }
}

3. 观察者模式（Observer Pattern）

设计意图：实现请求/响应的解耦监听。

// 拦截器观察者接口
export interface TCAPIManagerInterceptorListener {
  beforeRequestWithParams(params: Map<string, string>): void
  didReceiveResponse(data: ApiResponse): void
}

---

三、组件功能优势

3.1 分层职责清晰

层级	组件	职责
协议层	TCServiceProtocol, TCAPIManagerParamSettingListener	定义网关协议、参数配置契约
管理层	TCAPIBaseManager	请求生命周期管理、流程编排
HTTP层	AxiosHttpRequest, AxiosRequest	底层HTTP通信、拦截器配置
服务层	DefaultAPIService, DefaultBaseApi	默认实现、快速接入
工具层	LogUtils, CheckUtils, DataWrapUtils	日志、网络检测、数据转换

3.2 核心功能特性

1. 网络状态预检测

在请求发起前自动检测网络连接状态，避免无效请求：

request<T = CommonType>(config: HttpRequestConfig): Promise<T> {
  const isNet = await CheckUtils.getDeviceHasNet();
  if (!isNet) {
    let reason = getContext().resourceManager.getStringByNameSync('net_error_tip');
    reject({ message: reason });
    return;
  }
  // ...正常请求流程
}

2. 统一请求拦截器

支持请求前/后拦截，实现日志记录、Loading管理、Token注入等：

interceptorHooks: {
  requestInterceptor: async (config) => {
    LogUtils.info('请求链接:' + config.url);
    LogUtils.info('请求参数:' + JsonUtils.stringify(config.params));
    if (config.showLoading) {
      showLoadingDialog("加载中...")
    }
    return config;
  },
  responseInterceptor: (response) => {
    if (config.showLoading) {
      hideLoadingDialog()
    }
    if (response.status === 200 && response.data.errorCode != 0) {
      return Promise.reject(response)
    }
    return Promise.resolve(response.data);
  }
}

3. 灵活的网关定制

支持自定义网关实现加解密逻辑：

// 应用层自定义网关
export class ApiService extends DefaultAPIService {
  baseUrl: string = "https://www.wanandroid.com/";
  
  async requestWithParams(params: Map<string, string>, methodName: string, requestType: RequestType): Promise<Map<string, string>> {
    // 实现加密逻辑
    return params;
  }
  
  resultWithResponseObject(originResponse: ApiResponse): string {
    // 实现解密逻辑
    return response;
  }
}

4. 参数合法性校验

在请求前进行参数校验，避免脏数据：

async isCorrectWithParamsData(): Promise<boolean> {
  const hadNet = await CheckUtils.getDeviceHasNet()
  return hadNet;
}

5. 类型安全与泛型支持

完整的TypeScript类型定义，支持泛型响应：

export interface ApiResponse<T = CommonType> extends BaseResponse {
  data: T;
}

get<T = CommonType>(config: HttpRequestConfig): Promise<T> {
  config.method = 'GET'
  return this.request(config);
}

3.3 使用示例

第一步：定义业务API

export class DemoApi extends BaseApi {
  paramsForApi(): Map<string, CommonType> {
    let params = new Map<string, CommonType>()
    params.set("username", "test_zp")
    params.set("password", "123456")
    return params
  }

  methodName(): string {
    return 'user/login'
  }

  requestType(): RequestType {
    return RequestType.POST
  }
}

第二步：发起请求

let demoApi = new DemoApi()
demoApi.loadData()
  .then((data: string) => {
    console.info('接口请求成功：' + data)
  })
  .catch((err: string | Resource) => {
    console.error('接口请求失败：' + JSON.stringify(err))
  });

---

四、技术实现细节

4.1 请求流程图

4.2 类关系图

---

五、版本演进与更新记录

版本	日期	更新内容
V1.0.0	20240410	初始版本，支持GET/POST请求
V1.0.1	20240517	参数类型扩展为CommonType，支持number类型
V1.0.3	20240705	适配HarmonyOS 5.0，增加网络状态检测
V1.0.4	20240906	超时时间由10秒改为30秒
V1.1.x	20250809	持续迭代优化

---

、总结

lib_network 组件库通过分层架构和设计模式的组合应用，实现了：

1. 高扩展性：通过策略模式支持自定义网关协议
2. 低耦合：接口与实现分离，易于测试和维护
3. 易用性：简洁的API设计，快速接入业务代码
4. 健壮性：内置网络检测、参数校验、错误处理机制

该组件库已在多个鸿蒙项目中得到验证，是构建高质量鸿蒙应用的可靠网络请求解决方案。

---

技术栈：HarmonyOS NEXT SDK、TypeScript、@ohos/axios

运行环境：>=5.0.0(12) / >=HarmonyOS NEXT SDK Developer Preview2
项目地址：https://github.com/anomalyco/HarmonyCollection/tree/main/tcnetworkproject