▶_MiniApp Toolkit

uni-network

工具

uni-helper 组织出品的 uni-app 专用 Promise 风格 HTTP 客户端,支持请求/响应拦截器、自动类型推断、全局配置、文件上传下载、并发控制,是 uni-app 生态中 axios 风格的网络请求层最佳实践方案

uni-apphttprequestpromiseinterceptornetworkaxiostypescriptminiprogram

详细文档

资源概述#

@uni-helper/uni-networkuni-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 Stars127⭐
Forks16
npm 版本数35(latest: 0.24.2)
npm 最后发布2026-06-15
月下载量~895
许可证MIT
创建年份2022

设计规范#

API 设计哲学#

uni-network 遵循 axios API 设计理念,同时深度适配 uni-app 多平台特性:

code
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-networkluch-request
组织uni-helper 社区个人开发者 (lei-mu)
Stars127⭐667⭐
TypeScript✅ 原生泛型
拦截器请求 + 响应请求 + 响应
npm 版本3566
设计风格axios 风格axios 风格
文件上传✅ http.upload
下载✅ http.download

审核规范#

不适用(工具库,非平台类资源)

开发指南#

安装#

code
npm install @uni-helper/uni-network
# 或
pnpm add @uni-helper/uni-network
# 或
yarn add @uni-helper/uni-network

基础用法#

code
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');

文件上传与下载#

code
// 文件上传
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' }
});

拦截器高级用法#

code
// 并发控制:限制同时请求数
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);
});

常见陷阱#

  1. uni 全局对象依赖:确保在 uni-app 环境中使用,非 uni-app 项目无法运行
  2. 拦截器执行顺序:请求拦截器按注册顺序执行,响应拦截器按注册逆序执行(与 axios 一致)
  3. 响应数据结构:默认返回 { data, statusCode, header, config },需在响应拦截器中提取 response.data 简化使用
  4. 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):初始稳定版本,核心功能完成