
uni-network
工具uni-helper 组织出品的 uni-app 专用 Promise 风格 HTTP 客户端,支持请求/响应拦截器、自动类型推断、全局配置、文件上传下载、并发控制,是 uni-app 生态中 axios 风格的网络请求层最佳实践方案
uni-apphttprequestpromiseinterceptornetworkaxiostypescriptminiprogram
详细文档
资源概述#
@uni-helper/uni-network 是 uni-helper 开源社区组织出品的 uni-app 专用 Promise 风格 HTTP 客户端。它提供 axios 风格的 API 设计(http.get / http.post / http.interceptors),让 uni-app 开发者能在所有小程序平台 + H5 + App 上使用统一的网络请求层。
核心特性#
- Promise 风格 API:所有请求返回 Promise,告别回调地狱
- 请求/响应拦截器:全局鉴权、日志、错误处理,axios 风格中间件链
- 自动类型推断:TypeScript 泛型设计,
http.get<User>('/user')自动推断响应类型 - 全局配置:baseUrl / timeout / headers 全局设置 + 每次请求灵活覆盖
- 文件上传下载:原生
uni.uploadFile/uni.downloadFile的 Promise 封装 - 多平台兼容:微信 / 支付宝 / 百度 / 抖音 / QQ / 快手 / 京东小程序 + H5 + App
项目数据#
| 指标 | 数值 |
|---|---|
| GitHub Stars | 127⭐ |
| Forks | 16 |
| npm 版本数 | 35(latest: 0.24.2) |
| npm 最后发布 | 2026-06-15 |
| 月下载量 | ~895 |
| 许可证 | MIT |
| 创建年份 | 2022 |
设计规范#
API 设计哲学#
uni-network 遵循 axios API 设计理念,同时深度适配 uni-app 多平台特性:
import { createUniNetwork } from '@uni-helper/uni-network';
// 创建实例
const http = createUniNetwork({
baseUrl: 'https://api.example.com',
timeout: 10000,
headers: {
'Content-Type': 'application/json'
}
});
// 请求拦截器:统一鉴权
http.interceptors.request.use((config) => {
const token = uni.getStorageSync('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// 响应拦截器:统一错误处理
http.interceptors.response.use(
(response) => response.data,
(error) => {
if (error.statusCode === 401) {
uni.navigateTo({ url: '/pages/login/index' });
}
return Promise.reject(error);
}
);
// TypeScript 泛型请求
interface User { id: number; name: string }
const { data } = await http.get<User>('/user/1');
// data 自动推断为 User 类型
与 luch-request 对比#
| 维度 | uni-network | luch-request |
|---|---|---|
| 组织 | uni-helper 社区 | 个人开发者 (lei-mu) |
| Stars | 127⭐ | 667⭐ |
| TypeScript | ✅ 原生泛型 | ✅ |
| 拦截器 | 请求 + 响应 | 请求 + 响应 |
| npm 版本 | 35 | 66 |
| 设计风格 | axios 风格 | axios 风格 |
| 文件上传 | ✅ http.upload | ✅ |
| 下载 | ✅ http.download | ✅ |
审核规范#
不适用(工具库,非平台类资源)
开发指南#
安装#
npm install @uni-helper/uni-network
# 或
pnpm add @uni-helper/uni-network
# 或
yarn add @uni-helper/uni-network
基础用法#
import { createUniNetwork } from '@uni-helper/uni-network';
const http = createUniNetwork({
baseUrl: 'https://api.example.com'
});
// GET 请求
const { data: users } = await http.get('/users', {
params: { page: 1, size: 20 }
});
// POST 请求
const { data: result } = await http.post('/users', {
name: '张三',
email: 'zhangsan@example.com'
});
// PUT 请求
await http.put('/users/1', { name: '李四' });
// DELETE 请求
await http.delete('/users/1');
文件上传与下载#
// 文件上传
const { data } = await http.upload('/upload', {
filePath: tempFilePath,
name: 'file',
formData: {
userId: '123'
}
});
// 文件下载
const { data: fileData } = await http.download('/files/report.pdf', {
params: { token: 'xxx' }
});
拦截器高级用法#
// 并发控制:限制同时请求数
let activeRequests = 0;
const MAX_CONCURRENT = 5;
http.interceptors.request.use((config) => {
if (activeRequests >= MAX_CONCURRENT) {
return new Promise((resolve) => {
const timer = setInterval(() => {
if (activeRequests < MAX_CONCURRENT) {
clearInterval(timer);
activeRequests++;
resolve(config);
}
}, 100);
});
}
activeRequests++;
return config;
});
http.interceptors.response.use(
(response) => {
activeRequests--;
return response;
},
(error) => {
activeRequests--;
return Promise.reject(error);
}
);
// 自动重试(网络错误时)
http.interceptors.response.use(null, async (error) => {
const config = error.config;
if (!config.__retryCount) config.__retryCount = 0;
if (config.__retryCount >= 3) return Promise.reject(error);
config.__retryCount++;
await new Promise(r => setTimeout(r, 1000 * config.__retryCount));
return http(config);
});
常见陷阱#
- uni 全局对象依赖:确保在 uni-app 环境中使用,非 uni-app 项目无法运行
- 拦截器执行顺序:请求拦截器按注册顺序执行,响应拦截器按注册逆序执行(与 axios 一致)
- 响应数据结构:默认返回
{ data, statusCode, header, config },需在响应拦截器中提取response.data简化使用 - TypeScript 泛型:
http.get<T>()的 T 类型仅影响编译时类型检查,不做运行时数据转换
生态资源#
相关项目#
| 项目 | 说明 |
|---|---|
| luch-request | 另一热门 uni-app 请求库(667⭐) |
| alova | 请求策略层框架,支持 uni-app 适配器(4009⭐) |
| miniprogram-network | 微信原生小程序网络库(123⭐) |
| weapp-cookie | 小程序 Cookie 支持(849⭐) |
| vite-plugin-uni-pages | 同组织的 uni-app 路由方案(205⭐) |
uni-helper 生态#
uni-helper 是由多位 uni-app 社区核心贡献者组成的开源组织,致力于为 uni-app 生态提供高质量的开发工具:
- create-uni:项目脚手架(301⭐)
- vite-plugin-uni-pages:文件路由(205⭐)
- unocss-preset-uni:UnoCSS 预设(128⭐)
- uni-network:HTTP 客户端(127⭐)← 本条目
- uni-use:Vue3 组合式工具集(181⭐)
- uni-typed:TypeScript 类型增强(86⭐)
- axios-adapter:axios 适配器(58⭐)
版本更新#
- v0.24.2(2026-06-15):TypeScript 类型优化,修复拦截器类型推断问题
- v0.24.0(2026-05):重构拦截器系统,支持异步拦截器
- v0.20.0(2026-01):重大更新,API 设计对齐 axios v1.x
- v0.15.0(2025-10):新增文件上传/下载 Promise 封装
- v0.10.0(2025-06):初始稳定版本,核心功能完成