wangzai-request 工具使用指南

插件信息

插件ID：wangzai-request
版本号：1.0.0
功能：基于 uni-app 网络请求 API 封装的增强版请求库

简介

wangzai-request 是uni-app增强请求库，支持全HTTP方法、自动token认证、拦截器、文件传输、重试机制等。兼容Vue 3 + TypeScript，内置统一错误处理，支持H5/小程序/App多平台，可插件化全局使用。

功能特性

核心功能

支持多种 HTTP 方法：GET、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE、HEAD
请求/响应拦截器：统一处理请求前和响应后的逻辑
自动取消重复请求：避免重复请求导致的问题
请求配置合并：支持全局默认配置和单次请求配置
文件上传下载：便捷的文件上传和下载功能
超时设置：可自定义请求超时时间
重试机制：自动重试失败的请求
响应数据转换：支持自定义响应数据转换函数
取消令牌：支持手动取消请求
进度更新回调：实时获取上传/下载进度
基础 URL 配置：简化请求地址的编写
全局错误处理：统一处理网络错误和业务错误

技术特性

TypeScript 支持：完整的类型定义，提供良好的类型提示
Promise 化：基于 Promise 的 API 设计，支持 async/await
Vue 3 集成：支持插件方式安装和组合式 API 使用
灵活的配置：支持全局配置和单次请求配置
安全性：支持 SSL 证书验证和凭证携带

安装

第一步：请将request文件夹移入utils目录下

引入：推荐方式二

方式一：直接引入

// 引入默认实例
import request from './utils/request';

// 或引入具体方法
import { request, get, post, put, del, upload, download } from './utils/request';

方式二：Vue 插件安装

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { install as installRequest } from './utils/request';

const app = createApp(App);

// 安装插件（可选配置）
app.use(installRequest, {
  baseURL: 'https://api.example.com',
  timeout: 30000
});

app.mount('#app');

方式三：组合式 API

// 在组件中使用
import { useRequest } from './utils/request';

const request = useRequest();

基本使用

1. 发送 GET 请求

// 基本用法
request.get('/api/user', {
  params: { id: 1 }
}).then(response => {
  console.log('获取用户信息成功:', response);
}).catch(error => {
  console.error('获取用户信息失败:', error);
});

// 使用 async/await
async function getUserInfo() {
  try {
    const response = await request.get('/api/user', {
      params: { id: 1 }
    });
    console.log('获取用户信息成功:', response);
    return response;
  } catch (error) {
    console.error('获取用户信息失败:', error);
    throw error;
  }
}

2. 发送 POST 请求

// 基本用法
request.post('/api/user', {
  name: '张三',
  age: 25
}).then(response => {
  console.log('创建用户成功:', response);
}).catch(error => {
  console.error('创建用户失败:', error);
});

// 使用 async/await
async function createUser() {
  try {
    const response = await request.post('/api/user', {
      name: '张三',
      age: 25
    });
    console.log('创建用户成功:', response);
    return response;
  } catch (error) {
    console.error('创建用户失败:', error);
    throw error;
  }
}

3. 发送 PUT 请求

request.put('/api/user/1', {
  name: '李四',
  age: 26
}).then(response => {
  console.log('更新用户成功:', response);
});

4. 发送 DELETE 请求

request.delete('/api/user/1').then(response => {
  console.log('删除用户成功:', response);
});

5. 通用请求方法

request.request({
  url: '/api/user',
  method: 'POST',
  data: {
    name: '张三',
    age: 25
  },
  timeout: 10000,
  retry: 3
}).then(response => {
  console.log('请求成功:', response);
});

高级用法

1. 文件上传

request.upload({
  url: '/api/upload',
  filePath: 'xxx', // 文件路径
  name: 'file', // 文件名称
  formData: {
    userId: '1'
  },
  onProgressUpdate: (res) => {
    console.log('上传进度:', res.progress);
  }
}).then(response => {
  console.log('上传成功:', response);
});

2. 文件下载

request.download({
  url: '/api/download',
  filePath: 'xxx', // 保存路径
  onProgressUpdate: (res) => {
    console.log('下载进度:', res.progress);
  }
}).then(response => {
  console.log('下载成功:', response);
});

3. 取消请求

// 创建取消令牌
const { token, cancel } = request.createCancelToken();

// 发送请求
request.get('/api/user', {
  cancelToken: token
}).then(response => {
  console.log('请求成功:', response);
}).catch(error => {
  console.log('请求被取消:', error);
});

// 取消请求
setTimeout(() => {
  cancel('用户主动取消');
}, 1000);

4. 自定义响应数据转换

request.get('/api/user', {
  transformResponse: (data) => {
    // 自定义数据转换逻辑
    return {
      ...data,
      transformed: true
    };
  }
}).then(response => {
  console.log('转换后的响应数据:', response);
});

5. 创建新实例

const customRequest = request.create({
  baseURL: 'https://api.example.com',
  timeout: 30000,
  header: {
    'Content-Type': 'application/json',
    'X-Custom-Header': 'value'
  }
});

customRequest.get('/api/user').then(response => {
  console.log('请求成功:', response);
});

6. 取消所有请求

// 取消所有待处理的请求
request.cancelAll();

配置项说明

全局配置

配置项	类型	默认值	说明
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 工具默认配置了以下拦截器：

请求拦截器：自动从本地存储中获取 token 并添加到请求头中
响应拦截器：
- 统一处理业务错误（code !== 200）
- 处理 401 未授权访问，阻止继续处理
- 对其他错误显示错误提示，并根据 custom.catch 配置决定是否传递错误
- 统一处理网络错误，显示网络错误提示

自定义拦截器

// 获取拦截器实例
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);
  }
);

最佳实践

1. 统一 API 管理

// api/index.js
import request from '../utils/request';

export const userApi = {
  // 获取用户列表
  getUserList: (params) => request.get('/api/user/list', { params }),
  
  // 获取用户详情
  getUserDetail: (id) => request.get(`/api/user/${id}`),
  
  // 创建用户
  createUser: (data) => request.post('/api/user', data),
  
  // 更新用户
  updateUser: (id, data) => request.put(`/api/user/${id}`, data),
  
  // 删除用户
  deleteUser: (id) => request.delete(`/api/user/${id}`)
};

2. 统一错误处理

// 在响应拦截器中统一处理错误
const interceptors = request.getInterceptors();

interceptors.response.use(
  response => {
    return response;
  },
  error => {
    // 统一错误处理逻辑
    if (error.code === 401) {
      // 未授权处理
      uni.removeStorageSync('token');
      uni.reLaunch({ url: '/pages/login/index' });
    } else if (error.code === 403) {
      // 禁止访问处理
      uni.showToast({ title: '无权限访问', icon: 'none' });
    } else if (error.code === 404) {
      // 资源不存在处理
      uni.showToast({ title: '请求的资源不存在', icon: 'none' });
    } else {
      // 其他错误处理
      uni.showToast({ title: '网络错误，请稍后再试', icon: 'none' });
    }
    return Promise.reject(error);
  }
);

3. 请求重试策略

// 为特定请求设置重试策略
request.get('/api/user', {
  retry: 5, // 重试 5 次
  retryDelay: 2000 // 重试间隔 2 秒
}).then(response => {
  console.log('请求成功:', response);
});

4. 处理需要手动捕获错误的场景

// 当需要手动处理错误时，设置 custom.catch 为 true
request.post('/api/login', {
  username: 'admin',
  password: '123456'
}, {
  custom: {
    catch: true // 启用错误捕获
  }
}).then(response => {
  console.log('登录成功:', response);
}).catch(error => {
  console.error('登录失败:', error);
  // 手动处理登录失败的逻辑
});

常见问题

1. 如何设置基础 URL？

// 方法一：创建新实例时设置
const customRequest = request.create({
  baseURL: 'https://api.example.com'
});

// 方法二：单次请求时设置
request.get('/api/user', {
  baseURL: 'https://api.example.com'
});

2. 如何添加认证 token？

wangzai-request 工具默认会从本地存储中获取 token 并添加到请求头中。如果需要自定义 token 获取方式或修改 token 格式，可以修改请求拦截器：

const interceptors = request.getInterceptors();

interceptors.request.use(
  config => {
    const token = uni.getStorageSync('token');
    if (token) {
      // 默认格式：直接使用 token 值
      // config.header.Authorization = token;
      
      // 如需使用 Bearer 格式
      // config.header.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  error => {
    return Promise.reject(error);
  }
);

3. 如何处理跨域问题？

跨域问题需要在后端服务器上配置 CORS（跨域资源共享），前端可以通过设置 withCredentials 选项来携带凭证：

request.get('/api/user', {
  withCredentials: true
});

4. 如何设置超时时间？

// 方法一：全局设置
const customRequest = request.create({
  timeout: 30000 // 30秒
});

// 方法二：单次请求设置
request.get('/api/user', {
  timeout: 10000 // 10秒
});

5. 如何禁用默认的错误提示？

可以通过自定义响应拦截器来禁用默认的错误提示：

const interceptors = request.getInterceptors();

// 移除默认的响应拦截器
interceptors.response.clear();

// 添加自定义响应拦截器
interceptors.response.use(
  response => {
    const data = response.data;
    if (data.code !== 200) {
      // 自定义错误处理，不显示默认提示
      return Promise.reject(data);
    }
    return data;
  },
  error => {
    // 自定义网络错误处理，不显示默认提示
    return Promise.reject(error);
  }
);

总结

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

主要特性回顾

简洁易用的 API：支持链式调用和 async/await
强大的拦截器系统：统一处理请求和响应
智能的错误处理：自动识别和处理各种错误场景
灵活的配置选项：满足不同场景的需求
完善的 TypeScript 支持：提供良好的类型提示
Vue 3 集成：支持插件安装和组合式 API

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
request		request
LICENSE		LICENSE
README.md		README.md

License

zbybk/wangzai-request

Folders and files

Latest commit

History

Repository files navigation