miniprogram-network

miniprogram-network#

资源概述#

miniprogram-network 是一个专为微信小程序设计的网络请求库，对 wx.request、wx.downloadFile、wx.uploadFile 进行了全面重新封装。它提供 Promise 化的 API、完整的 TypeScript 类型推断，以及自动重试、缓存、取消令牌、自定义超时、离线暂停、全局拦截器和事件监听等企业级功能。

核心特点：

Promise + 泛型：所有网络操作返回 Promise<T> 泛型，完整类型推断，无 any
自动重试（Retry）：网络错误时自动重试，支持自定义重试策略（间隔/次数/条件）
缓存（Cache）：底层缓存支持，并发请求自动合并（防抖），避免重复请求
取消令牌（CancelToken）：支持取消正在进行的请求（类似 axios CancelToken）
离线感知：自动检测网络状态，离线或切换到后台时暂停请求，恢复后自动发送
拦截器（Interceptors）：transformSend / transformResponse 自定义数据拦截转换
全局事件监听（Listeners）：onSend / onResponse / onRejected / onAbort / onComplete 五种事件
按需引入：可只安装 miniprogram-request / miniprogram-downloader / miniprogram-uploader 子包，减小包体

项目数据（2026-08-10）：

GitHub：123⭐ / 11 forks / Apache-2.0 License
npm：最新版 5.3.0 / 83 versions
活跃度：最后推送 2025-07-18
语言：TypeScript

设计规范#

架构设计#

miniprogram-network 采用三层架构：

层级	说明	示例
核心层	配置管理、拦截器、事件、CancelToken	`setConfig()`、`Interceptor`
操作层	三种网络操作的独立封装	`REQUEST`、`DOWNLOAD`、`UPLOAD`
便捷层	快捷方法	`get()`、`post()`、`download()`

每个操作类型（REQUEST/DOWNLOAD/UPLOAD）拥有独立的 Defaults 配置，可分别设置不同的默认参数。

子包拆分#

包名	功能	安装
`miniprogram-network`	完整包（request + download + upload）	`npm i miniprogram-network`
`miniprogram-request`	仅 HTTP 请求	`npm i miniprogram-request`
`miniprogram-downloader`	仅文件下载	`npm i miniprogram-downloader`
`miniprogram-uploader`	仅文件上传	`npm i miniprogram-uploader`

审核规范#

miniprogram-network 是开发工具库，不涉及平台审核。使用时需注意：

拦截器中不应修改请求的敏感字段（如 token、签名），除非有明确的安全策略
缓存功能可能存储接口返回的用户数据，需根据数据敏感程度决定是否启用
全局 baseURL 配置确保指向正确的后端环境（开发/预发/生产）

开发指南#

快速上手#

1. 安装

code

# 完整安装
npm install miniprogram-network

# 或按需安装（减小包体）
npm install miniprogram-request  # 仅 HTTP 请求

2. 全局配置 + 基础请求

code

import { setConfig, REQUEST, get, post } from 'miniprogram-network'

// 全局默认配置
setConfig('baseURL', 'https://api.example.com/')
setConfig('timeout', 15000)
setConfig('retry', 3) // 网络错误自动重试 3 次

// 自动提取 response.data（2xx 视为成功）
REQUEST.Defaults.transformResponse = (res, options) => {
  if (res.statusCode >= 200 && res.statusCode < 300) {
    return res.data
  }
  throw new Error(`HTTP ${res.statusCode}`)
}

// GET 请求（返回 Promise + 泛型）
interface User { id: number; name: string }
get<User>('users/1').then(user => {
  console.log(user.name) // TypeScript 推断为 string
})

// POST 请求
post('users', { name: '张三', age: 25 })
  .then(res => console.log('创建成功'))
  .catch(err => console.error(err))

3. 模板参数 + 重试

code

import { patch } from 'miniprogram-network'

// URL 模板参数绑定
patch('items/{id}', { dataKey: 'dataValue' }, {
  params: { id: 123456 },  // 自动替换 {id}
  retry: 3,                // 本次请求重试 3 次
}).then(item => console.log(item))

4. 下载文件（带进度回调）

code

import { download, transformDownloadResponseOkData } from 'miniprogram-network'

download('files/document.pdf', 'wx://local/path', {
  onProgressUpdate: (res) => {
    console.log(`下载进度: ${res.progress}%`)
  },
  transformResponse: transformDownloadResponseOkData, // 2xx 返回本地路径
}).then(path => console.log('已保存到:', path))

5. 拦截器（transformSend / transformResponse）

code

import { REQUEST } from 'miniprogram-network'

// 请求拦截：自动添加 token
REQUEST.Defaults.transformSend = (options) => {
  const token = wx.getStorageSync('token')
  options.header = { ...options.header, Authorization: `Bearer ${token}` }
  return options
}

// 响应拦截：统一错误处理
REQUEST.Defaults.transformResponse = (res, options) => {
  if (res.statusCode === 401) {
    wx.navigateTo({ url: '/pages/login/index' })
    throw new Error('未授权')
  }
  return res.data
}

6. 自定义重试策略

code

import { REQUEST, delayRetry } from 'miniprogram-network'

// 间隔 1s 重试，最多 2 次
REQUEST.Defaults.retry = delayRetry(1000, 2)

// 自定义重试条件（仅对网络错误重试，不对 4xx 重试）
REQUEST.Defaults.retry = (err, retryCount) => {
  if (retryCount >= 3) return false
  return err.errMsg?.includes('timeout') || err.errMsg?.includes('network')
}

常见陷阱#

transformResponse 的返回值就是 Promise resolve 的值 — 如果你返回 res.data，调用方拿到的就是 res.data，不是完整的 res
缓存默认按 URL 做 key — 如果不同参数用同一 URL（如 POST body 不同），需在 options 中禁用缓存或自定义 cacheKey
离线暂停仅对通过库发起的请求生效 — 直接调用 wx.request 不会被暂停
CancelToken 需手动管理 — 页面卸载时取消未完成请求，否则会触发 onRejected 回调
子包引入时 API 不同 — miniprogram-request 的导入方式与完整包不同，需查看对应文档

生态资源#

竞品对比#

方案	Stars	定位	TypeScript	重试	缓存	取消	拦截器
miniprogram-network	123⭐	小程序原生网络层重封装	✅ 原生	✅	✅	✅	✅
luch-request	uni-app 生态	uni-app 请求库（基于 uni.request）	✅	✅	❌	❌	✅
axios-miniprogram-adapter	297⭐	axios 小程序适配器	✅	✅（axios 内置）	❌	✅	✅
alova	4009⭐	请求策略层框架（跨端）	✅	✅	✅	✅	✅

选型建议#

场景	推荐
微信原生小程序 + 企业级网络需求	miniprogram-network
uni-app 项目	luch-request（uni-app 官方推荐）
已有 axios 经验/代码迁移	axios-miniprogram-adapter
跨端 + 高级请求策略（分页/表单/SSE）	alova

社区资源#

GitHub Issues — 问题反馈
GitHub Wiki — 扩展文档
npm：miniprogram-network
npm：miniprogram-request（子包）

版本更新#

v5.3.0（最新）#

TypeScript 类型定义完善
离线检测优化
缓存并发合并改进
Apache-2.0 License

v5.x 核心特性#

Promise + 泛型完整支持
自动重试（可自定义策略）
缓存（含并发请求合并）
CancelToken 取消机制
拦截器（transformSend / transformResponse）
全局事件监听（5 种事件）
按需子包引入
离线感知 + 后台暂停

发展趋势#

miniprogram-network 最后推送在 2025-07-18，距今约 1 年。核心功能稳定，83 个 npm versions 说明经过充分迭代。虽社区规模较小（123⭐），但在微信小程序网络层封装领域是功能最全面的方案之一。如需更活跃维护的替代方案，可关注 alova（4009⭐，2026-07 仍活跃）。

详细文档