当前位置：首页 > news >正文

HarmonyOS ArkTS开发实战：用Axios封装一个带拦截器的网络请求工具类

news 2026/5/29 2:24:42

HarmonyOS ArkTS实战：构建企业级Axios网络请求工具库

在HarmonyOS应用开发中，网络请求作为数据交互的核心通道，其稳定性和可维护性直接影响应用质量。本文将带你从零构建一个支持Token自动刷新、错误统一处理的Axios企业级封装库，结合ArkTS特性实现类型安全的网络请求体系。不同于基础教程，我们更关注工程化实践中的典型问题解决方案。

1. 企业级网络请求架构设计

现代移动应用对网络层的要求早已超越简单的数据收发。我们需要考虑以下核心要素：

认证管理：JWT令牌的自动刷新机制
错误处理：服务端异常、网络异常的标准化处理
性能监控：请求耗时统计与性能优化
安全防护：参数加密、重试策略等

先看基础架构设计：

class HttpService { private instance: AxiosInstance; private retryCount = 0; private tokenRefreshPromise: Promise<string> | null = null; constructor() { this.instance = axios.create({ baseURL: 'https://api.example.com', timeout: 10000 }); this.setupInterceptors(); } }

关键设计要点：

单例模式：确保全局唯一实例
私有化构造：防止外部直接实例化
状态隔离：各实例保持独立配置

2. 拦截器深度封装实践

2.1 请求拦截器实现

典型企业应用需要处理以下场景：

private setupRequestInterceptor() { this.instance.interceptors.request.use( (config: InternalAxiosRequestConfig) => { // 添加认证头 if (this.getToken()) { config.headers!['Authorization'] = `Bearer ${this.getToken()}`; } // 请求时间标记 config.metadata = { startTime: Date.now() }; // 参数签名处理 if (config.data) { config.data.sign = this.generateSign(config.data); } return config; }, (error) => { return Promise.reject(error); } ); }

2.2 响应拦截器最佳实践

响应处理需要区分业务错误和系统错误：

private setupResponseInterceptor() { this.instance.interceptors.response.use( (response: AxiosResponse) => { // 性能监控 const endTime = Date.now(); const duration = endTime - response.config.metadata.startTime; monitor.recordApiPerformance(response.config.url!, duration); // 业务状态码处理 if (response.data.code !== 200) { return this.handleBusinessError(response); } return response.data; }, (error: AxiosError) => { return this.handleSystemError(error); } ); }

错误处理策略矩阵：

错误类型	状态码范围	处理方式	用户提示
认证失效	401	触发刷新令牌	"登录状态已过期"
权限不足	403	跳转权限页面	"无访问权限"
服务异常	500-599	自动重试3次	"服务暂时不可用"
网络超时	ECONNABORTED	检查网络设置	"网络连接超时"

3. Token自动刷新机制

JWT认证体系下，令牌刷新是高频需求。我们需要解决：

避免并发刷新请求
处理刷新期间的请求排队
刷新失败后的降级策略

实现方案：

private async handleTokenRefresh(error: AxiosError) { const originalRequest = error.config!; // 判断是否需要刷新（401错误且非刷新请求） if (error.response?.status !== 401 || originalRequest.url === '/refresh_token') { return Promise.reject(error); } // 防止并发刷新 if (!this.tokenRefreshPromise) { this.tokenRefreshPromise = this.refreshToken(); } try { const newToken = await this.tokenRefreshPromise; originalRequest.headers!['Authorization'] = `Bearer ${newToken}`; return this.instance(originalRequest); } catch (refreshError) { // 刷新失败跳转登录 router.navigateToLogin(); return Promise.reject(refreshError); } finally { this.tokenRefreshPromise = null; } }

关键流程控制：

请求拦截：检测401状态码
并发控制：通过Promise缓存避免重复刷新
队列处理：等待期间的新请求挂起
结果应用：更新请求头重新发起

4. ArkTS类型安全实践

ArkTS的强类型特性要求我们特别注意类型定义：

4.1 响应数据类型封装

interface BaseResponse<T = any> { code: number; message: string; data: T; timestamp: number; } class HttpService { async get<T>(url: string, config?: AxiosRequestConfig): Promise<T> { return this.instance.get<BaseResponse<T>>(url, config) .then(res => res.data.data); } async post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> { return this.instance.post<BaseResponse<T>>(url, data, config) .then(res => res.data.data); } }

4.2 业务错误类型定义

enum ErrorCode { SUCCESS = 200, BAD_REQUEST = 400, UNAUTHORIZED = 401, FORBIDDEN = 403, NOT_FOUND = 404, INTERNAL_ERROR = 500 } class BusinessError extends Error { constructor( public code: ErrorCode, message: string, public details?: any ) { super(message); } }

类型安全带来的优势：

编译时发现参数类型错误
自动补全响应字段
明确的错误处理路径

5. 高级功能实现

5.1 请求取消与竞态处理

class HttpService { private cancelTokenSources: Map<string, CancelTokenSource> = new Map(); requestWithCancel(key: string, config: AxiosRequestConfig) { // 取消重复请求 this.cancelPreviousRequest(key); const source = axios.CancelToken.source(); this.cancelTokenSources.set(key, source); return this.instance({ ...config, cancelToken: source.token }).finally(() => { this.cancelTokenSources.delete(key); }); } private cancelPreviousRequest(key: string) { const source = this.cancelTokenSources.get(key); if (source) { source.cancel(`Request ${key} canceled`); this.cancelTokenSources.delete(key); } } }

5.2 文件上传进度监控

async uploadFile(url: string, file: File, onProgress?: (percent: number) => void) { const formData = new FormData(); formData.append('file', file); return this.instance.post(url, formData, { headers: { 'Content-Type': 'multipart/form-data' }, onUploadProgress: (progressEvent) => { if (progressEvent.total && onProgress) { const percent = Math.round( (progressEvent.loaded * 100) / progressEvent.total ); onProgress(percent); } } }); }

5.3 缓存策略实现

interface CacheConfig { ttl?: number; // 缓存有效期(ms) forceRefresh?: boolean; // 强制刷新 } class HttpService { private cacheStore = new Map<string, { data: any; expire: number; }>(); async getWithCache<T>( url: string, config?: AxiosRequestConfig & CacheConfig ): Promise<T> { const cacheKey = this.generateCacheKey(url, config?.params); // 强制刷新或缓存过期 if (config?.forceRefresh || !this.isCacheValid(cacheKey)) { const response = await this.get<T>(url, config); this.cacheStore.set(cacheKey, { data: response, expire: Date.now() + (config?.ttl || 300000) }); return response; } return this.cacheStore.get(cacheKey)!.data; } }

6. 测试与调试技巧

6.1 Mock服务配置

// 测试环境配置 if (process.env.NODE_ENV === 'test') { axios.defaults.adapter = require('axios-mock-adapter'); const mock = new MockAdapter(axios); mock.onGet('/user').reply(200, { id: 1, name: '测试用户' }); }

6.2 网络日志记录

private setupDebugInterceptor() { this.instance.interceptors.request.use(config => { console.log('[Request]', config.method?.toUpperCase(), config.url); return config; }); this.instance.interceptors.response.use(response => { console.log('[Response]', response.status, response.config.url); return response; }, error => { console.error('[Error]', error.message); return Promise.reject(error); }); }

调试信息分级策略：

级别	输出内容	适用场景
DEBUG	完整请求/响应数据	开发环境
INFO	关键路径日志	测试环境
WARN	异常警告	预发环境
ERROR	错误堆栈	生产环境

7. 性能优化方案

7.1 请求合并技术

class BatchRequest { private batchQueue: Array<{ key: string; params: any; resolve: (value: any) => void; reject: (reason?: any) => void; }> = []; private timer: number | null = null; addRequest(key: string, params: any) { return new Promise((resolve, reject) => { this.batchQueue.push({ key, params, resolve, reject }); if (!this.timer) { this.timer = setTimeout(() => this.flush(), 50); } }); } private async flush() { const items = [...this.batchQueue]; this.batchQueue = []; this.timer = null; try { const results = await this.sendBatchRequest(items); items.forEach((item, index) => { item.resolve(results[index]); }); } catch (error) { items.forEach(item => { item.reject(error); }); } } }

7.2 连接池优化

// 底层适配器配置 const httpAdapter = require('axios/lib/adapters/http'); const https = require('https'); const agent = new https.Agent({ keepAlive: true, maxSockets: 20, maxFreeSockets: 10, timeout: 60000 }); axios.create({ adapter: httpAdapter, httpsAgent: agent });

性能指标对比：