Vue3 + Vite项目实战：手把手教你封装一个带Token自动管理的Axios请求库

Vue3 Vite项目实战打造企业级Axios请求库的自动化设计在当今前端工程化实践中一个健壮的HTTP请求库早已不是简单的请求发送工具而是承载着Token管理、错误处理、性能监控等多项职责的基础设施。本文将带您从工程化角度重构一个真正具备生产级质量的请求库解决方案。1. 请求库架构设计理念现代前端项目的HTTP请求库需要解决三个核心问题自动化、可维护性和一致性。我们先来看一个典型的请求生命周期中需要处理的环节graph TD A[发起请求] -- B[Token注入] B -- C[参数处理] C -- D[实际请求] D -- E[状态码处理] E -- F[数据格式化] F -- G[错误处理]基于这个流程我们的请求库需要实现以下关键特性智能Token管理自动注入、刷新和失效处理统一错误处理网络异常、业务异常的分类处理请求生命周期钩子提供各个阶段的扩展点类型安全完整的TypeScript支持性能监控请求耗时统计和异常上报2. 核心实现方案2.1 创建增强型Axios实例不同于基础封装我们需要创建一个具备扩展能力的Axios实例// src/libs/http-client.ts import axios from axios import type { AxiosInstance, AxiosRequestConfig } from axios class HttpClient { private instance: AxiosInstance private interceptors: HttpInterceptors constructor(config: HttpRequestConfig) { this.instance axios.create(config) this.interceptors config.interceptors || {} this.setupInterceptors() } private setupInterceptors() { // 请求拦截器链 this.instance.interceptors.request.use( this.interceptors.request?.success, this.interceptors.request?.failure ) // 响应拦截器链 this.instance.interceptors.response.use( this.interceptors.response?.success, this.interceptors.response?.failure ) } public requestT(config: HttpRequestConfig): PromiseT { return this.instance.request(config) } // 其他HTTP方法封装... } export default HttpClient2.2 Token自动化管理实现Token的自动注入和刷新机制需要考虑多种场景// Token管理策略 const tokenStrategy { getToken(): string | null { // 从存储中获取 }, refreshToken(): Promisestring { // 调用刷新接口 }, shouldRefresh(error): boolean { // 判断是否需要刷新 }, isExpired(token): boolean { // 检查Token过期 } } // 请求队列管理 const pendingRequests new Map() // 拦截器配置 instance.interceptors.request.use(async (config) { if (config.requireAuth ! false) { let token tokenStrategy.getToken() if (token tokenStrategy.isExpired(token)) { if (!pendingRequests.has(refreshing)) { pendingRequests.set(refreshing, true) token await tokenStrategy.refreshToken() pendingRequests.delete(refreshing) } else { return new Promise((resolve) { const unsubscribe () { pendingRequests.delete(waiting) resolve(instance(config)) } pendingRequests.set(waiting, unsubscribe) }) } } config.headers.Authorization Bearer ${token} } return config })2.3 智能错误处理系统建立分级的错误处理机制错误类型处理方式用户提示网络错误自动重试/跳转网络设置网络连接不可用401未授权清除Token跳转登录登录已过期403禁止访问提示权限不足无访问权限500服务器错误上报异常/展示备用UI服务暂时不可用业务逻辑错误透传错误码根据业务码显示对应提示// 错误处理器 class ErrorHandler { static handle(error) { if (error.isAxiosError) { switch (error.response?.status) { case 401: this.handleUnauthorized() break case 403: this.handleForbidden() break // 其他状态码处理... } } // 业务错误处理 if (error.bizCode) { showToast(error.bizMessage) } // 异常上报 trackError(error) } }3. 高级功能实现3.1 请求取消与竞态处理实现请求防抖和取消机制// 请求取消令牌管理 const cancelTokenMap new Map() function createCancelToken(key: string) { if (cancelTokenMap.has(key)) { cancelTokenMap.get(key).cancel() } const source axios.CancelToken.source() cancelTokenMap.set(key, source) return source.token } // 使用示例 async function fetchData(params) { try { const res await request({ url: /api/data, cancelToken: createCancelToken(data-request) }) // 处理数据 } catch (err) { if (!axios.isCancel(err)) { // 处理真实错误 } } }3.2 性能监控集成在拦截器中加入性能统计instance.interceptors.request.use((config) { config.metadata { startTime: Date.now() } return config }) instance.interceptors.response.use( (response) { const duration Date.now() - response.config.metadata.startTime trackApiPerformance({ url: response.config.url, duration, status: response.status }) return response }, (error) { if (error.config) { const duration Date.now() - error.config.metadata.startTime trackApiPerformance({ url: error.config.url, duration, status: error.response?.status || 0, isError: true }) } return Promise.reject(error) } )4. 工程化实践建议4.1 配置管理最佳实践推荐的项目配置结构src/ libs/ http-client/ # 请求库核心 index.ts # 主入口 interceptors/ # 拦截器实现 types/ # 类型定义 utils/ # 工具函数 config/ http.ts # HTTP相关配置 env.ts # 环境变量处理环境变量处理方案// config/env.ts export function getApiBaseUrl() { return import.meta.env.VITE_API_BASE ?? /api } export function getApiTimeout() { return Number(import.meta.env.VITE_API_TIMEOUT) || 10000 }4.2 团队协作规范制定团队内的HTTP请求规范API定义规范所有API必须定义在src/api目录下按业务模块组织文件结构必须使用TypeScript接口定义请求/响应类型错误处理规范业务错误必须包含错误码和用户友好提示网络错误要有统一的重试机制敏感错误不上报具体信息性能优化建议列表接口默认启用分页大数据量响应启用压缩频繁调用的接口考虑本地缓存5. 测试与调试技巧5.1 Mock方案对比方案优点缺点适用场景Mock Service Worker浏览器层拦截最接近真实配置复杂开发环境全量MockVite Proxy Mock零配置修改即时生效功能有限快速原型开发本地JSON文件简单直接无法模拟动态场景静态数据模拟推荐使用Mock Service Worker进行API模拟// src/mocks/handlers.ts import { rest } from msw export const handlers [ rest.get(/api/user, (req, res, ctx) { return res( ctx.delay(150), ctx.json({ id: user-1, name: John Doe }) ) }) ]5.2 调试工具链配置推荐在开发环境中添加以下调试支持// vite.config.js export default defineConfig({ plugins: [ { name: configure-response, configureServer(server) { server.middlewares.use((req, res, next) { res.setHeader(Access-Control-Expose-Headers, X-Request-Id) next() }) } } ] })在Chrome开发者工具中可以通过自定义日志标签过滤请求// 在请求拦截器中 console.log( %cAPI Request%c %s %o, background: #4CAF50; color: white; padding: 2px 4px; border-radius: 3px;, , config.method?.toUpperCase(), { url: config.url, params: config.params, data: config.data } )6. 性能优化策略6.1 请求缓存实现基于内存的缓存方案const cache new Map() async function cachedRequest(config) { const cacheKey JSON.stringify({ url: config.url, params: config.params }) if (cache.has(cacheKey)) { return cache.get(cacheKey) } const response await instance.request(config) cache.set(cacheKey, response) // 设置过期时间 setTimeout(() { cache.delete(cacheKey) }, config.cacheTTL || 30000) return response }6.2 压缩与性能调优推荐配置const instance axios.create({ // 启用请求体压缩 decompress: true, // 优化大JSON响应 transformResponse: [ (data) { try { return JSONbig.parse(data) } catch { return data } } ], // DNS缓存 httpAgent: new http.Agent({ keepAlive: true }), httpsAgent: new https.Agent({ keepAlive: true }) })7. 安全加固方案7.1 常见安全防护CSRF防护自动注入XSRF-TOKENCSP合规检查响应头安全策略敏感信息过滤拦截器中的日志过滤// 安全拦截器 const securityInterceptor { onRequest(config) { // 过滤敏感字段 if (config.data?.password) { config.data.password [REDACTED] } return config }, onResponse(response) { // 检查安全头 if (!response.headers[content-security-policy]) { reportSecurityIssue(Missing CSP header) } return response } }7.2 敏感操作保护关键操作需要二次确认function withConfirmation(requestFn, message) { return async function(...args) { await confirmDialog(message) return requestFn(...args) } } // 使用示例 const deleteUser withConfirmation( (userId) request.delete(/users/${userId}), 确认删除该用户 )8. 项目集成示例8.1 Vue3组合式API集成创建可复用的HTTP Hook// src/composables/useHttp.ts export function useHttp() { const loading ref(false) const error ref(null) const request async (config) { loading.value true error.value null try { const response await httpClient.request(config) return response } catch (err) { error.value err throw err } finally { loading.value false } } return { loading, error, request } }8.2 Pinia状态管理集成将请求状态纳入状态管理// stores/api.ts export const useApiStore defineStore(api, { state: () ({ pendingRequests: 0, lastError: null }), actions: { async callApi(config) { this.pendingRequests try { const response await httpClient.request(config) this.lastError null return response } catch (error) { this.lastError error throw error } finally { this.pendingRequests-- } } } })9. 演进路线规划9.1 架构演进方向微前端适配支持多实例共存主子应用通信桥接Serverless集成云函数调用封装自动凭证管理GraphQL适配层查询批处理缓存策略集成9.2 性能监控扩展建议增加的监控维度请求成功率统计慢请求分析依赖服务健康度检查用户端网络质量采样// 监控插件示例 const monitoringPlugin { install(httpClient) { httpClient.interceptors.response.use( (response) { reportSuccess(response) return response }, (error) { reportError(error) return Promise.reject(error) } ) } }10. 疑难问题解决方案10.1 常见问题排查问题1Token刷新竞态条件解决方案let refreshPromise null async function getToken() { if (tokenExpired()) { if (!refreshPromise) { refreshPromise refreshToken().finally(() { refreshPromise null }) } return refreshPromise } return currentToken }问题2文件上传进度丢失解决方案const uploadFile (file, onProgress) { const formData new FormData() formData.append(file, file) return request.post(/upload, formData, { onUploadProgress: (progressEvent) { const percent Math.round( (progressEvent.loaded * 100) / progressEvent.total ) onProgress(percent) } }) }10.2 调试技巧推荐使用以下Chrome开发者工具技巧网络请求过滤使用domain:api.example.com过滤特定域名请求使用larger-than:1M查找大体积请求性能分析使用Performance面板记录请求瀑布流检查Timing标签中的各个阶段耗时断点调试// 在请求拦截器中添加debugger instance.interceptors.request.use((config) { if (config.url.includes(/sensitive)) { debugger } return config })11. 前沿技术展望11.1 WebSocket集成方案实现实时数据与HTTP请求的统一管理class HybridClient { private http: HttpClient private socket: WebSocket constructor() { this.http new HttpClient() this.socket new WebSocket(wss://api.example.com) this.setupSocket() } private setupSocket() { this.socket.onmessage (event) { this.emit(message, JSON.parse(event.data)) } } public request(config) { if (config.realtime) { return new Promise((resolve) { const handler (data) { if (data.id config.id) { this.off(message, handler) resolve(data) } } this.on(message, handler) this.socket.send(JSON.stringify(config)) }) } return this.http.request(config) } }11.2 Server-Sent Events适配处理服务器推送事件function createEventSource(url) { const eventSource new EventSource(url) return { onMessage(handler) { eventSource.onmessage (event) { handler(JSON.parse(event.data)) } }, close() { eventSource.close() } } }12. 移动端适配策略12.1 弱网处理方案实现离线优先策略const offlineCache new Map() async function offlineRequest(config) { if (navigator.onLine) { try { const response await request(config) offlineCache.set(config.cacheKey, response) return response } catch (err) { if (offlineCache.has(config.cacheKey)) { return offlineCache.get(config.cacheKey) } throw err } } else if (offlineCache.has(config.cacheKey)) { return offlineCache.get(config.cacheKey) } throw new Error(Offline and no cached data) }12.2 请求优先级管理基于业务重要性的优先级队列class PriorityQueue { private high: Array() Promiseany private normal: Array() Promiseany private low: Array() Promiseany add(task: () Promiseany, priority: high | normal | low) { this[priority].push(task) this.process() } private processing false private async process() { if (this.processing) return this.processing true while (this.high.length || this.normal.length || this.low.length) { const task this.high.shift() || this.normal.shift() || this.low.shift() try { await task() } catch (err) { console.error(Queue task failed:, err) } } this.processing false } }13. 微前端场景适配13.1 主子应用通信通过自定义事件实现跨应用通信// 主应用 window.mainAppBridge { request: (config) httpClient.request(config) } // 子应用 function proxyRequest(config) { if (window.mainAppBridge) { return window.mainAppBridge.request(config) } return localRequest(config) }13.2 共享实例方案// 共享模块 let sharedInstance null export function getSharedHttpClient() { if (!sharedInstance) { sharedInstance new HttpClient({ baseURL: /api, interceptors: { request: [authInterceptor], response: [errorInterceptor] } }) } return sharedInstance }14. 测试策略设计14.1 单元测试重点测试关键拦截器逻辑describe(Auth Interceptor, () { it(should add token to headers, async () { localStorage.setItem(token, test-token) const instance axios.create() instance.interceptors.request.use(authInterceptor) const config await instance.interceptors.request.handlers[0].fulfilled({ headers: {} }) expect(config.headers.Authorization).toBe(Bearer test-token) }) })14.2 E2E测试方案使用Cypress进行API测试// cypress/e2e/api.cy.js describe(API Suite, () { it(should handle auth failure, () { cy.intercept(POST, /auth, { statusCode: 401, body: { code: AUTH_FAILED } }) cy.visit(/login) cy.get(#submit).click() cy.contains(.error, 认证失败).should(be.visible) }) })15. 部署与运维15.1 健康检查方案实现API健康监控端点// 健康检查路由 router.get(/health, (req, res) { const checks { database: checkDatabase(), cache: checkCache(), thirdParty: checkThirdPartyAPI() } Promise.all(Object.values(checks)) .then(() res.status(200).json({ status: healthy })) .catch(() res.status(500).json({ status: unhealthy })) })15.2 灰度发布支持通过Header控制请求路由instance.interceptors.request.use((config) { if (localStorage.getItem(beta-user) true) { config.headers[X-API-Version] v2 } return config })16. 性能优化进阶16.1 请求合并策略实现类似GraphQL的批处理class BatchRequest { private batch: Array{ config: any, resolve: Function, reject: Function } [] private timer: any null add(config) { return new Promise((resolve, reject) { this.batch.push({ config, resolve, reject }) if (!this.timer) { this.timer setTimeout(() this.flush(), 50) } }) } private async flush() { const batch this.batch this.batch [] this.timer null try { const response await axios.post(/batch, { requests: batch.map(item item.config) }) batch.forEach((item, index) { item.resolve(response.data.results[index]) }) } catch (err) { batch.forEach(item item.reject(err)) } } }16.2 预加载方案基于路由的API预加载router.beforeEach((to) { if (to.meta.preloadApis) { to.meta.preloadApis.forEach(api { api.load() }) } }) // 路由配置示例 { path: /dashboard, component: Dashboard, meta: { preloadApis: [userApi, statsApi] } }17. 安全防护进阶17.1 请求签名方案防止请求篡改function createSign(config) { const timestamp Date.now() const nonce Math.random().toString(36).slice(2) const str [ config.method, config.url, timestamp, nonce, JSON.stringify(config.data) ].join(|) const sign crypto .createHmac(sha256, SECRET_KEY) .update(str) .digest(hex) config.headers[X-Timestamp] timestamp config.headers[X-Nonce] nonce config.headers[X-Sign] sign return config }17.2 敏感操作审计记录关键操作日志instance.interceptors.request.use((config) { if (config.sensitive) { auditLog({ action: config.url, params: config.data, user: currentUser }) } return config })18. 监控体系集成18.1 全链路追踪实现请求链路追踪instance.interceptors.request.use((config) { const traceId generateTraceId() config.headers[X-Trace-Id] traceId startTrace(traceId, config) return config }) instance.interceptors.response.use( (response) { endTrace(response.config.headers[X-Trace-Id], success) return response }, (error) { if (error.config) { endTrace(error.config.headers[X-Trace-Id], failed) } return Promise.reject(error) } )18.2 性能指标采集采集关键性能指标const metrics { requestCount: 0, successCount: 0, errorCount: 0, durationSum: 0 } instance.interceptors.response.use( (response) { metrics.requestCount metrics.successCount metrics.durationSum response.duration return response }, (error) { metrics.requestCount metrics.errorCount return Promise.reject(error) } ) // 定期上报 setInterval(() { reportMetrics({ ...metrics, avgDuration: metrics.durationSum / metrics.requestCount }) }, 60000)19. 国际化支持19.1 多语言错误处理根据用户语言返回错误信息class I18nErrorHandler { static messages { en-US: { 401: Unauthorized, 404: Not Found }, zh-CN: { 401: 未授权, 404: 资源不存在 } } static handle(error, lang en-US) { const message this.messages[lang]?.[error.status] || error.message showToast(message) } }19.2 区域化配置不同区域的API配置function getRegionalConfig() { const timezone Intl.DateTimeFormat().resolvedOptions().timeZone const region timezone.startsWith(Asia) ? APAC : EMEA return { baseURL: REGION_CONFIG[region].apiBase, timeout: REGION_CONFIG[region].timeout } }20. 设计模式应用20.1 策略模式应用可插拔的拦截器策略interface InterceptorStrategy { onRequest?(config): any; onResponse?(response): any; onError?(error): any; } class InterceptorManager { private strategies: InterceptorStrategy[] [] use(strategy: InterceptorStrategy) { this.strategies.push(strategy) } apply(instance) { instance.interceptors.request.use( (config) this.strategies.reduce((c, s) s.onRequest?.(c) ?? c, config) ) instance.interceptors.response.use( (response) this.strategies.reduce((r, s) s.onResponse?.(r) ?? r, response), (error) this.strategies.reduceRight((e, s) s.onError?.(e) ?? e, error) ) } }20.2 装饰器模式应用增强请求功能function withRetry(times 3) { return function(target, key, descriptor) { const original descriptor.value descriptor.value async function(...args) { let lastError for (let i 0; i times; i) { try { return await original.apply(this, args) } catch (error) { lastError error await new Promise(resolve setTimeout(resolve, 1000 * i)) } } throw lastError } return descriptor } } class ApiService { withRetry(3) async fetchData() { return request.get(/data) } }