Uniapp请求封装踩坑记：从uni.addInterceptor到Promise封装，这些细节Vue3+TS开发者一定要注意

Uniapp请求封装深度避坑指南Vue3TS开发者的实战复盘第一次在Uniapp项目中尝试封装网络请求时我踩过的坑可能比写过的有效代码还多。从拦截器莫名失效到TypeScript类型飘红从Promise链断裂到错误处理混乱——如果你也在Vue3TS环境下为uni.request的封装头疼这篇血泪经验或许能帮你省下三天调试时间。1. 拦截器陷阱为什么你的uni.addInterceptor不生效很多开发者习惯性地把axios的封装经验直接套用到Uniapp结果发现拦截器配置像被黑洞吞噬了一样毫无反应。关键在于理解Uniapp拦截器与axios的本质差异// 典型错误示例试图用axios风格创建实例 const instance uni.createRequest({...}) // 根本不存在这个方法正确姿势是使用uni.addInterceptor但要注意这些魔鬼细节调用时机必须在所有uni.request调用前注册拦截器建议在App.vue的onLaunch中初始化参数合并策略拦截器中的配置会被后续请求参数浅合并这意味着uni.addInterceptor(request, { invoke(args) { args.header { X-Custom: default } // 会被后续请求完全覆盖 } }) // 正确做法使用展开运算符保留原有header args.header { ...args.header, X-Custom: default }路径拼接的坑当同时存在拦截器路径修改和手动传递完整URL时可能产生重复拼接// 拦截器内 if (!args.url.startsWith(http)) { args.url baseURL args.url // 危险可能被多次执行 } // 解决方案添加标记位或使用URL对象校验 const isAbsoluteURL /^[a-z][a-z0-9.-]*:/.test(args.url)2. TypeScript类型体操让泛型真正发挥作用看到这样的类型定义TS新手可能会直接崩溃type ApiResponseT { code: number message: string data: T // 但实际响应中还混着pageSize/total等字段... }实战中更健壮的做法是分层定义类型// 基础响应结构 type BaseResponseT any { success: boolean errCode?: string errMsg?: string data: T } // 分页数据特殊处理 type PaginatedDataT { list: T[] page: number size: number total: number } // 实际使用时的完整类型 type UserListResponse BaseResponsePaginatedDataUser对于uni.request的封装需要特别注意泛型透传问题function requestT(options: UniApp.RequestOptions): PromiseT { return new Promise((resolve, reject) { uni.request({ ...options, success: (res) { // 这里需要类型断言 const data res.data as BaseResponseT if (data.success) { resolve(data.data) // 自动推导为T类型 } else { reject(data) } } }) }) } // 使用时获得完美类型提示 const users await requestUser[]({ url: /api/users }) // ^? User[] 类型3. Promise封装的艺术避免掉入异步陷阱直接返回uni.request的Promise是危险的因为成功回调里HTTP状态码可能仍是400业务错误和网络错误混在一起缺乏统一的加载状态管理更健壮的封装方案应当包含class HttpError extends Error { constructor( public code: number, public message: string, public raw?: any ) { super(message) } } async function safeRequestT(options: UniApp.RequestOptions): PromiseT { try { const response await new PromiseUniApp.RequestSuccessCallbackResult((resolve, reject) { uni.request({ ...options, success: resolve, fail: reject }) }) // HTTP层错误处理 if (response.statusCode 200 || response.statusCode 300) { throw new HttpError( response.statusCode, HTTP Error: ${response.statusCode}, response ) } const data response.data as BaseResponseT // 业务层错误处理 if (!data.success) { throw new HttpError( data.errCode || UNKNOWN, data.errMsg || Unknown error, data ) } return data.data } catch (error) { // 统一错误处理 if (error instanceof HttpError) { showToast(error.message) if (error.code 401) { navigateToLogin() } } else { showToast(网络连接异常) } throw error // 继续向上抛出供业务层捕获 } }关键改进点区分HTTP错误和业务错误自定义错误类包含完整上下文统一处理常见错误场景仍然保留错误的可捕获性4. 实战中的性能优化技巧当项目规模增长后基础封装可能遇到性能瓶颈4.1 取消重复请求const pendingRequests new Mapstring, AbortController() function generateRequestKey(config: UniApp.RequestOptions): string { return ${config.method}-${config.url}-${JSON.stringify(config.data)} } async function requestWithCancelT(options: UniApp.RequestOptions): PromiseT { const key generateRequestKey(options) const controller new AbortController() // 取消重复请求 if (pendingRequests.has(key)) { pendingRequests.get(key)?.abort() } pendingRequests.set(key, controller) try { const response await request({ ...options, signal: controller.signal }) return response } finally { pendingRequests.delete(key) } }4.2 请求缓存策略const cache new Mapstring, { timestamp: number data: any promise?: Promiseany }() async function cachedRequestT(options: UniApp.RequestOptions { cacheTime?: number }): PromiseT { const key generateRequestKey(options) const now Date.now() const cacheTime options.cacheTime || 30000 // 默认30秒 if (cache.has(key)) { const entry cache.get(key)! // 未过期且已有数据 if (now - entry.timestamp cacheTime data in entry) { return entry.data } // 正在请求中 if (entry.promise) { return entry.promise } } const promise requestT(options).then(data { cache.set(key, { timestamp: now, data }) return data }) cache.set(key, { timestamp: now, promise }) return promise }4.3 并发控制class RequestQueue { private maxConcurrent: number private running 0 private queue: Array() void [] constructor(maxConcurrent 5) { this.maxConcurrent maxConcurrent } async enqueueT(task: () PromiseT): PromiseT { if (this.running this.maxConcurrent) { return this.runTask(task) } return new Promise((resolve, reject) { this.queue.push(() { this.runTask(task).then(resolve).catch(reject) }) }) } private async runTaskT(task: () PromiseT): PromiseT { this.running try { return await task() } finally { this.running-- this.dequeue() } } private dequeue() { if (this.queue.length this.running this.maxConcurrent) { const nextTask this.queue.shift()! nextTask() } } } // 全局请求队列 const globalQueue new RequestQueue() // 使用示例 async function queuedRequest(options: UniApp.RequestOptions) { return globalQueue.enqueue(() request(options)) }在大型Uniapp项目中这些优化手段可以将网络请求效率提升200%以上。特别是在列表页快速滑动、选项卡繁切换等场景下能有效避免重复请求和内存泄漏。