wx-request-plus

一个功能强大的微信小程序请求库，对wx.request进行了全面增强，提供更优雅的API和丰富的功能。

✨ 主要特性

• 🚀 完整的TypeScript支持 - 类型安全的API调用，智能提示
• ⛓️ Promise风格API - 告别回调地狱，优雅处理异步
• 💾 智能缓存机制 - LRU缓存策略，优化请求性能
• 📶 弱网环境支持 - 离线队列，自动重试，网络恢复自动发送
• 🚦 请求队列管理 - 控制并发，设置优先级，避免请求风暴
• 🔀 并发请求支持 - 使用all方法同时发送多个请求，提高效率
• 🔮 预请求支持 - 提前加载数据，瞬时响应用户操作
• 🛡️ 拦截器机制 - 全局处理请求和响应，统一错误处理
• 🔍 自动提取响应字段 - 简化数据获取，直达核心内容
• 🔄 智能重试机制 - 网络错误自动重试，指数退避策略
• ❌ 请求取消支持 - 取消不需要的请求，优化资源利用
• 🔧 高度可定制化 - 更多适应各种复杂场景的灵活配置
• 💥 强大的错误处理 - 详细的错误类型和信息，便于调试和处理

安装

1npm install wx-request-plus --save

在小程序中引入

确保你的小程序项目配置中启用了 npm 支持：

1. 在微信开发者工具中，点击【工具】->【构建npm】
2. 在 request.ts 中引入：

1// request.ts
2import WxRequest from 'wx-request-plus';
3
4const wxRequest = WxRequest.create({
5  baseURL: ENV.PROD,
6  timeout: 4000
7});
8
9export default wxRequest

基本使用

创建请求实例

1import WxRequest from 'wx-request-plus';
2
3// 推荐方式: 使用静态工厂方法创建实例
4const wxRequest = WxRequest.create({
5  baseURL: 'https://api.example.com',
6  timeout: 5000,
7  headers: {
8    'Content-Type': 'application/json'
9  }
10});
11
12// 也可以使用构造函数方式
13// const wxRequest = new WxRequest({...});

发起请求

1// 发起GET请求
2wxRequest.get('/users')
3  .then(res => {
4    console.log('用户数据:', res.data);
5  })
6  .catch(err => {
7    console.error('请求失败:', err);
8  });
9
10// 发起POST请求
11wxRequest.post('/users', {name: '张三', age: 25})
12  .then(res => {
13    console.log('创建成功:', res.data);
14  });
15
16// 在页面组件中使用
17import wxRequest from './request';
18
19Page({
20  onLoad() {
21    wxRequest.get('/products')
22      .then(res => {
23        this.setData({
24          products: res.data
25        });
26      });
27  }
28})

功能特性

支持多种请求方式

1// 便捷方法
2wxRequest.get('/users');
3wxRequest.post('/users', { name: '张三' });
4wxRequest.put('/users/1', { name: '李四' });
5
6// 通用request方法
7wxRequest.request({
8  url: '/users',
9  method: 'GET',
10  params: { role: 'admin' }
11});
12
13// 灵活参数
14wxRequest.request('/users');  // GET请求
15wxRequest.request('/users', { name: '张三' });  // POST请求带数据

自动提取响应字段

自动提取标准API响应中的特定字段，简化数据处理流程。

1// 全局配置自动提取data字段
2const wxRequest = WxRequest.create({
3  baseURL: 'https://api.example.com',
4  extractField: 'data' // 自动提取response.data
5});
6
7// 单次请求配置
8wxRequest.get('/users', {
9  extractField: 'data.list'  // 提取嵌套字段
10});
11
12wxRequest.get('/raw', {
13  skipExtract: true  // 跳过提取，获取原始响应
14});
15
16// 使用自定义提取函数
17wxRequest.get('/custom', {
18  extractField: (data) => data.result.items.filter(item => item.active)
19});

强大的缓存机制

支持多种缓存策略，在弱网环境下提供更好的用户体验。

1// 使用缓存
2wxRequest.get('/config', { 
3  cache: true,              // 启用缓存
4  cacheExpire: 60000        // 缓存60秒
5});
6
7// 缓存模式
8wxRequest.get('/users', { 
9  cache: 'force-cache'      // 强制使用缓存，优先从缓存读取
10});
11
12wxRequest.get('/profile', { 
13  cache: 'only-if-cached'   // 只使用缓存，没有缓存则报错
14});
15
16// 清除缓存
17wxRequest.clearCache();

并发请求

使用all方法可以同时发送多个请求，并在所有请求完成后统一处理结果。

1// 并发请求示例
2const request1 = wxRequest.get('/users');
3const request2 = wxRequest.get('/products');
4const request3 = wxRequest.post('/orders', { id: 123 });
5
6// 使用async/await
7async function fetchData() {
8  const [users, products, order] = await wxRequest.all([
9    wxRequest.get('/users'),
10    wxRequest.get('/products'),
11    wxRequest.post('/orders', { id: 123 })
12  ]);
13  
14  console.log('用户列表:', users.data);
15  console.log('产品列表:', products.data);
16  console.log('订单详情:', order.data);
17}

请求和响应拦截器

拦截请求和响应，进行全局处理，如添加认证信息、统一错误处理等。

1// 请求拦截器
2wxRequest.interceptors.request.use(
3  config => {
4    // 添加token
5    config.headers = { 
6      ...config.headers,
7      'Authorization': `Bearer ${wx.getStorageSync('token')}` 
8    };
9    // 对GET请求默认启用缓存
10    if (config.method?.toUpperCase() === 'GET' && config.cache === undefined) {
11      config.cache = true;
12    }
13    return config;
14  },
15  error => {
16    return Promise.reject(error);
17  }
18);
19
20// 使用响应拦截器可以统一处理错误
21wxRequest.interceptors.response.use(
22  response => response,
23  error => {
24    // 根据错误类型处理
25    switch(error.type) {
26      case ErrorType.TIMEOUT:
27        console.error('请求超时', error.config.url);
28        break;
29      case ErrorType.NETWORK:
30        console.error('网络连接错误', error.config.url);
31        break;
32      case ErrorType.SERVER:
33        console.error('服务器错误', error.status, error.config.url);
34        break;
35      case ErrorType.CLIENT:
36        console.error('客户端错误', error.status, error.config.url);
37        break;
38    }
39    
40    // 可以选择继续抛出错误或返回特定值
41    return Promise.reject(error);
42  }
43);
44

错误重试和网络状态管理

智能处理网络错误，支持自动重试和网络状态监控。

1// 全局配置重试
2const wxRequest = WxRequest.create({
3  retryTimes: 3,     // 最大重试次数
4  retryDelay: 1000   // 重试间隔(ms)
5});
6
7// 单次请求配置
8wxRequest.get('/important-api', {
9  retry: 5,  // 指定重试次数
10  retryDelay: 2000,  // 重试间隔
11  retryIncrementalDelay: true  // 递增延迟
12});
13
14// 获取网络状态
15wxRequest.getNetworkStatus().then(status => {
16  console.log('当前网络状态:', status.isConnected, status.networkType);
17});

请求取消

支持取消正在进行的请求，避免不必要的网络开销。

1// 取消特定请求
2wxRequest.cancelRequests(config => config.url.includes('/users'));
3
4// 取消所有请求和加载提示
5wxRequest.cancelAll();

API文档

配置选项

参数	类型	描述	默认值
baseURL	string	请求的基础URL	''
timeout	number	超时时间(ms)	10000
headers	object	默认请求头	{'Content-Type': 'application/json'}
maxCacheSize	number	最大缓存条目数	100
maxCacheAge	number	默认缓存过期时间(ms)	5分钟
retryTimes	number	全局默认重试次数	3
retryDelay	number	全局默认重试延迟	1000
enableQueue	boolean	是否启用请求队列	true
maxConcurrent	number	最大并发请求数	10
enableOfflineQueue	boolean	无网络时是否进入离线队列	true
extractField	string/function	自动提取响应字段	undefined
returnData	boolean	是否直接返回数据而非Response对象	false

版本兼容性

• 支持的微信基础库版本: 2.2.1+
• TypeScript版本: 4.0+

许可证

MIT