引言

在移动应用开发中，网络请求是不可或缺的一部分。无论是数据获取、用户认证还是文件上传下载，都需要一个稳定、高效、易用的网络请求库。对于 uni-app 开发者来说，虽然官方提供了 `uni.request` API，但在实际开发中，我们常常需要处理诸如请求拦截、响应统一处理、错误捕获、自动重试等复杂场景，这些都需要额外的封装和处理。

为了解决这些问题，我开发了 wangzai-request 工具，这是一个基于 uni-app 网络请求 API 封装的增强版请求库，旨在为开发者提供更简洁、更强大、更灵活的网络请求解决方案。

---

什么是wangzai-request

它是专为uniapp生态打造的网络请求增强库，它不仅保留了原生 API 的所有功能，还添加了许多实用的特性，如自动 token 认证、请求/响应拦截器、文件传输、重试机制等。同时，它完全兼容 Vue 3 + TypeScript，内置统一错误处理，支持 H5/小程序/App 多平台，可插件化全局使用。

---

核心功能

1、全面的HTTP方法支持

支持 GET、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE、HEAD 等全 HTTP 方法，满足各种请求场景需求。

2、强大的拦截器系统

请求拦截器：可在请求发送前统一处理配置，如自动添加 token、设置请求头等。

响应拦截器：可在响应返回后统一处理数据，如错误处理、数据转换等

3、智能的错误处理

统一处理网络错误和业务错误

自动识别 401 未授权等特殊错误

可配置的错误提示策略

4、实用的高级特性

自动取消重复请求：避免重复请求导致的问题

请求重试机制：自动重试失败的请求

文件上传下载：便捷的文件上传和下载功能，支持进度回调

取消令牌：支持手动取消请求

基础 URL 配置：简化请求地址的编写

响应数据转换：支持自定义响应数据转换函数

5、技术优势

TypeScript 支持：完整的类型定义，提供良好的类型提示

Promise 化：基于 Promise 的 API 设计，支持 async/await

Vue 3 集成：支持插件方式安装和组合式 API 使用

灵活的配置：支持全局配置和单次请求配置

安全性：支持 SSL 证书验证和凭证携带

---

快速上手

获取工具

方式一：通过插件市场获取，访问此处，下载插件并导入HbuilderX。  

方式二：通过GitHub获取，访问此处，下载插件。

安装

一、在项目根目录下创建utils目录

二、将工具内的request文件移入utils目录

若从插件市场获取到的工具将会在js_sdk目录下。将request文件移动至utils路径下。

三、引入工具并进行配置

import { install as installRequest } from '@/utils/request' // 引入wangzai-request

// 安装wangzai-request插件
installRequest(app, {
	baseURL: '', // 配置基础URL，示例：https://app.xxx.com/
})

复制以上代码在mian.uts文件中粘贴。以下是main.uts完整文件：

import App from './App.uvue'

import { createSSRApp } from 'vue'

import { install as installRequest } from '@/utils/request' // 引入wangzai-request

export function createApp() {
	const app = createSSRApp(App)

	// 安装wangzai-request插件
	installRequest(app, {
		baseURL: 'https://app.xxx.com/', // 配置基础URL
	})

	return {
		app
	}
}

注：baseURL可在main.uts中安装插件的时候赋值，也可在core.ts文件中定义baseURL。

使用

GET请求

1、基本用法

uni.showLoading({
	title: '请稍后',
	mask: true
})
this.$request.get('/app/goods/list').then(res => {
	console.log('res', res.data)
}).catch(err => {
	console.log('err', err)
}).finally(fi => {
	uni.hideLoading()
})

2、携带请求参数，需要注意get请求参数需要放在params中进行传递。

uni.showLoading({
	title: '请稍后',
	mask: true
})
this.$request.get('/app/goods/list', {
	params: {
		pageSize: 5,
		pageNum: 1
	},
}).then(res => {
	console.log('res', res)
}).catch(err => {
	console.log('err', err)
}).finally(fi => {
	uni.hideLoading()
})

3、局部配置，局部配置的优先级高于全局配置（例：全局默认配置重试次数为3次，但是局部配置了重试次数为5次，那么此请求失败后将会重试5次。）

uni.showLoading({
	title: '请稍后',
	mask: true
})
this.$request.get('/youlian/app/goods/list', {
	params: {
		pageSize: 5,
		pageNum: 1
	},
	retry: 5, //重试 5 次
	retryDelay: 3000 //重试间隔 3 秒
    /* 局部配置的优先级高于全局配置 */
}).then(res => {
	console.log('res', res)
}).catch(err => {
	console.log('err', err)
}).finally(fi => {
	uni.hideLoading()
})

POST请求

1、基本用法

uni.showLoading({
	title: '请稍后',
	mask: true
})
this.$request.post('/app/login', {
	username: 'testuser',
	password: '123456'
}).then(res => {
	console.log('res', res.data)
}).catch(err => {
	console.log('err', err)
}).finally(fi => {
	uni.hideLoading()
})

2、局部配置，get请求的所有参数都在方法的第二个参数中，而post请求的第二个参数为请求参数params，而第三个参数才会作为局部配置项。

uni.showLoading({
	title: '请稍后',
	mask: true
})
this.$request.post('/app/login', {
	username: 'testuser',
	password: '123456'
} , {
	retry: 5, //重试 5 次
	retryDelay: 3000 //重试间隔 3 秒
}).then(res => {
	console.log('res', res.data)
}).catch(err => {
	console.log('err', err)
}).finally(fi => {
	uni.hideLoading()
})

---

拦截器

默认拦截器

此工具默认配置了以下拦截器：

1、请求拦截器：自动从本地存储中获取token并添加至请求头中。

2、响应拦截器：

• 统一处理业务错误（code!==200）
• 处理401未授权访问，阻止继续处理
• 对其他错误显示错误提示，并根据custom.catch 配置决定是否传递错误
• 统一处理网络错误，显示网络错误提示

拦截器在index.ts文件中，可自行配置或删除。

自定义拦截器

// 获取拦截器实例
const interceptors = request.getInterceptors();

// 添加请求拦截器
interceptors.request.use(
  config => {
    // 在发送请求前做些什么
    console.log('请求拦截器:', config);
    return config;
  },
  error => {
    // 对请求错误做些什么
    console.error('请求错误:', error);
    return Promise.reject(error);
  }
);

// 添加响应拦截器
interceptors.response.use(
  response => {
    // 对响应数据做点什么
    console.log('响应拦截器:', response);
    return response;
  },
  error => {
    // 对响应错误做点什么
    console.error('响应错误:', error);
    return Promise.reject(error);
  }
);

---

错误处理

网络错误

当网络请求失败时（如网络断开、超时等），wangzai-request 工具会自动显示错误提示，并将错误传递给 catch 回调。

业务错误

当后端返回业务错误时（如 code !== 200），wangzai-request 工具会：

• 对于 401 错误：阻止继续处理，不会进入 catch 回调
• 对于其他错误：显示错误提示，并根据 custom.catch 配置决定是否传递错误
  • 当 custom.catch 为 true 时：错误会传递到 catch 回调
  • 当 custom.catch 为 false 或未设置时：不会进入 catch 回调

自定义错误处理

可以通过响应拦截器自定义错误处理逻辑：

const interceptors = request.getInterceptors();

interceptors.response.use(
  response => {
    // 自定义成功处理
    return response;
  },
  error => {
    // 自定义错误处理
    console.error('自定义错误处理:', error);
    return Promise.reject(error);
  }
);

 

---

配置项说明

全局配置

配置项	类型	默认值	说明
baseURL	string	''	基础 URL
timeout	number	60000	超时时间（毫秒）
header	Record<string, string>	{ 'Content-Type': 'application/json' }	请求头
dataType	'json' 'text'	'json'	数据类型
responseType	'text' 'arraybuffer'	'text'	响应类型
sslVerify	boolean	true	是否验证 SSL 证书
withCredentials	boolean	false	是否携带凭证
firstIpv4	boolean	false	是否优先使用 IPv4
transformResponse	(data: any) => any	undefined	响应数据转换函数
custom	Record<string, any>	undefined	自定义配置

局部配置（单次请求配置）

配置项	类型	默认值	说明
url	string	-	请求地址
data	any	undefined	请求数据
method	'GET' 'POST' 'PUT' 'DELETE' 'CONNECT' 'OPTIONS' 'TRACE' 'HEAD'	'GET'	请求方法
timeout	number	60000	超时时间（毫秒）
retry	number	3	重试次数，0 表示不重试
retryDelay	number	1000	重试间隔（毫秒）
cancelToken	CancelToken	undefined	取消令牌
signal	AbortSignal	undefined	中止信号
onProgressUpdate	(res: UniApp.OnProgressUpdateCallbackResult) => void	undefined	进度更新回调
baseURL	string	''	基础 URL
header	Record<string, string>	{ 'Content-Type': 'application/json' }	请求头
dataType	'json' 'text'	'json'	数据类型
responseType	'text' 'arraybuffer'	'text'	响应类型
sslVerify	boolean	true	是否验证 SSL 证书
withCredentials	boolean	false	是否携带凭证
firstIpv4	boolean	false	是否优先使用 IPv4
transformResponse	(data: any) => any	undefined	响应数据转换函数
custom	Record<string, any>	undefined	自定义配置

---

总结

wangzai-request 工具是一个功能强大、使用便捷的网络请求库，它提供了丰富的特性和灵活的配置选项，帮助开发者更高效地处理网络请求。通过本指南的学习，相信你已经掌握了 wangzai-request 工具的基本使用方法和高级特性，可以在实际项目中灵活运用它来处理各种网络请求场景。