从零构建高可维护的TypeScript请求库axios企业级封装实战每次在Vue3项目中新建一个页面你是否习惯性打开旧项目复制粘贴网络请求代码当接口字段变更时是否需要在十几个文件中逐个修改错误处理逻辑这种重复劳动不仅降低开发效率更会成为项目维护的噩梦。本文将带你从工程化角度用TypeScript打造一个开箱即用、易于扩展的axios请求库彻底告别碎片化的请求代码。1. 为什么需要封装axios前端项目中网络请求就像空气一样无处不在。但直接使用原生axios会导致以下问题代码重复每个请求都需要重复编写错误处理、loading状态管理类型缺失响应数据没有类型约束后期维护如同盲人摸象难以维护拦截器逻辑分散在各处修改时需全局搜索替换扩展困难新需求如缓存、重试等特性无法统一实现我们的封装目标是通过面向对象设计实现以下特性// 理想中的调用方式 const user await http.getUser(/api/user, { cache: true // 自动缓存控制 })2. 基础架构设计2.1 类型系统先行优秀的TS封装始于严谨的类型定义。我们先规划核心类型// 基础响应结构 interface ApiResponseT unknown { code: number data: T message?: string } // 扩展的请求配置 interface RequestConfig extends AxiosRequestConfig { showLoading?: boolean retryCount?: number } // 错误处理类型 class RequestError extends Error { code?: number isNetworkError?: boolean }2.2 类结构设计采用工厂模式创建请求实例便于后续多实例管理class RequestClient { private instance: AxiosInstance private interceptors: RequestInterceptors constructor(config: RequestConfig) { this.instance axios.create(config) this.setupInterceptors() } private setupInterceptors() { // 拦截器实现 } public getT(url: string, config?: RequestConfig): PromiseT { // 方法实现 } // 其他HTTP方法... }3. 拦截器深度优化3.1 请求拦截器实战现代前端应用通常需要处理以下请求逻辑this.instance.interceptors.request.use(config { // 1. 认证处理 const token auth.getToken() if (token) { config.headers.Authorization Bearer ${token} } // 2. 全局loading控制 if (config.showLoading ! false) { store.dispatch(showLoading) } // 3. 特殊header处理 if (config.url?.includes(/upload)) { config.headers[Content-Type] multipart/form-data } return config })3.2 响应拦截器最佳实践响应处理需要兼顾业务约定和异常情况this.instance.interceptors.response.use( response { // 1. 关闭loading store.dispatch(hideLoading) // 2. 处理二进制响应 if (response.config.responseType blob) { return response.data } // 3. 业务状态码处理 const { code, data, message } response.data if (code 200) return data return Promise.reject( new RequestError(message || 业务错误, { code }) ) }, error { // 统一错误处理 const requestError new RequestError() if (error.response) { // HTTP状态码错误 requestError.code error.response.status requestError.message this.mapErrorCode(error.response.status) } else if (error.request) { // 网络错误 requestError.isNetworkError true requestError.message 网络连接异常 } else { // 其他错误 requestError.message error.message } return Promise.reject(requestError) } )4. 高级功能扩展4.1 请求重试机制对于不稳定的网络环境自动重试能显著提升用户体验private async requestWithRetryT( method: HttpMethod, url: string, config?: RequestConfig ): PromiseT { let retryCount config?.retryCount || 0 while (retryCount 0) { try { return await this.request(method, url, config) } catch (error) { if (!this.shouldRetry(error) || retryCount 0) { throw error } retryCount-- await new Promise(resolve setTimeout(resolve, this.getRetryDelay(retryCount)) ) } } throw new RequestError(请求失败) }4.2 缓存控制实现合理利用缓存可以减轻服务器压力private cache new Mapstring, { expire: number data: any }() public async getT( url: string, config?: RequestConfig { cacheTTL?: number } ): PromiseT { const cacheKey this.generateCacheKey(url, config) if (config?.cacheTTL) { const cached this.cache.get(cacheKey) if (cached cached.expire Date.now()) { return cached.data } } const data await this.request(get, url, config) if (config?.cacheTTL) { this.cache.set(cacheKey, { data, expire: Date.now() config.cacheTTL * 1000 }) } return data }5. 项目集成实践5.1 Vue3组合式API封装在组合式函数中提供更优雅的调用方式// src/composables/useHttp.ts export default function useHttp() { const http new RequestClient({ baseURL: import.meta.env.VITE_API_URL }) const get async T(url: string, config?: RequestConfig) { try { return await http.getT(url, config) } catch (error) { // 统一UI错误处理 showToast(error.message) throw error } } return { get } }5.2 环境变量管理通过环境变量支持多环境配置# .env.development VITE_API_URLhttps://dev.api.example.com VITE_API_TIMEOUT5000 # .env.production VITE_API_URLhttps://api.example.com VITE_API_TIMEOUT10000const http new RequestClient({ baseURL: import.meta.env.VITE_API_URL, timeout: Number(import.meta.env.VITE_API_TIMEOUT) })6. 测试与调试技巧6.1 单元测试策略使用jest编写健壮的测试用例describe(RequestClient, () { let http: RequestClient beforeEach(() { http new RequestClient({ baseURL: https://api.example.com }) jest.clearAllMocks() }) test(should add auth header when token exists, async () { localStorage.setItem(token, test-token) const spy jest.spyOn(axios, create) new RequestClient({}) expect(spy.mock.calls[0][0].headers.Authorization) .toBe(Bearer test-token) }) })6.2 调试拦截器在Chrome开发者工具中可以通过以下方式调试在拦截器代码处打上断点使用axios的请求/响应日志功能通过performance标记观察请求时间线// 在请求拦截器中添加性能标记 window.performance.mark(request_start)7. 性能优化与安全7.1 取消重复请求防止快速点击导致的重复提交private pendingRequests new Mapstring, AbortController() private addPendingRequest(config: RequestConfig) { const key this.generateRequestKey(config) if (this.pendingRequests.has(key)) { this.pendingRequests.get(key)?.abort() } const controller new AbortController() config.signal controller.signal this.pendingRequests.set(key, controller) }7.2 CSRF防护自动处理CSRF token// 在请求拦截器中 const csrfToken getCookie(csrfToken) if (csrfToken [post, put, delete].includes(config.method!)) { config.headers[X-CSRF-Token] csrfToken }8. 项目目录结构建议规范的目录结构有助于长期维护src/ libs/ http/ index.ts # 主入口 types.ts # 类型定义 interceptors/ # 拦截器实现 auth.ts error.ts loading.ts plugins/ # 扩展功能 cache.ts retry.ts utils/ # 工具函数 helper.ts test/ http/ http.test.ts9. 未来扩展方向当基础请求库稳定后可以考虑集成GraphQL客户端支持添加WebSocket连接管理实现请求优先级队列开发可视化请求监控面板interface AdvancedConfig { priority?: low | normal | high analytics?: boolean }在大型项目中我们进一步将请求库与状态管理结合实现了请求自动缓存到Vuex的功能。当组件卸载时自动取消pending请求显著降低了内存泄漏风险。经过三个版本的迭代现在这个请求库已经支撑了公司所有前端项目平均为每个新项目节省了40%的网络请求相关代码量。