19:21

uni-app 轻量级 Http 请求库 v0.0.19+

支持 TypeScript、Vue3、组合式 API，插件化、全局配置、请求/响应拦截器、toast/loading 灵活控制，开箱即用，适合中小型项目。目前不适用于其他的请求形式，比如上传，下载等。

平台兼容性

App	H5	微信小程序	支付宝小程序	百度小程序	头条小程序	QQ小程序
√	√	√	√	√	√	√

提示

put/delete 在某些小程序平台的限制：

• 1.delete 请求，不支持支付宝和头条小程序(HX2.6.15)
• 2.put 请求，不支持支付宝小程序(HX2.6.15)

特性亮点

• 支持 get/post/put/delete 四种常用请求
• 插件化注册，支持全局配置和拦截器
• toast、loading 可全局/单次请求灵活配置
• 拦截器支持 token 注入、统一错误处理、登录失效跳转等
• TypeScript 类型友好，支持组合式 API
• 可通过 $u.http.get/post 方式调用（需 import { $u } from 'uview-pro'）
• 适配 H5、App、各主流小程序平台

基本用法

组合式 API

import { http } from 'uview-pro'

// GET
http.get('/api/user', { id: 1 }).then(res => {
  /* ... */
})

// POST
http.post('/api/login', { username: 'xx', password: 'xx' }).then(res => {
  /* ... */
})

// PUT/DELETE
http.put('/api/user/1', { name: 'new' })
http.delete('/api/user/1')

await/async

const res = await http.post('/api/login', { username: 'xx' })

自定义 header

http.get(
  '/api/user',
  {},
  {
    header: { Authorization: 'Bearer token' }
  }
)

全局与动态配置

全局配置

import { http } from 'uview-pro'

http.setConfig({
  baseUrl: 'https://api.example.com',
  meta: {
    toast: true, // 全局开启错误toast，默认为false关闭
    loading: true, // 全局开启loading，默认为false关闭
    originalData: true // 是否在拦截器中返回服务端的原始数据，默认为true返回的是原始数据
  }
})

单次请求动态配置

http.post(
  '/api/login',
  { username: 'xx' },
  {
    meta: { toast: true, loading: true }
  }
)

最佳实践-推荐

1. 创建拦截器文件

import type { RequestConfig, RequestInterceptor, RequestMeta, RequestOptions } from 'uview-pro'
import { useUserStore } from '@/store'

// 全局请求配置
export const httpRequestConfig: RequestConfig = {
  baseUrl,
  header: {
    'content-type': 'application/json'
  },
  meta: {
    originalData: true,
    toast: true,
    loading: true
  }
}

// 全局请求/响应拦截器
export const httpInterceptor: RequestInterceptor = {
  request: (config: RequestOptions) => {
    const meta: RequestMeta = config.meta || {}
    if (meta.loading) {
      // 显示loading
    }
    const userStore = useUserStore()
    if (userStore.token) {
      config.header.Authorization = `Bearer ${userStore.token}`
    }
    return config
  },
  response: (response: any) => {
    const meta: RequestMeta = response.config?.meta || {}
    if (meta.loading) {
      // 隐藏loading
    }

    // 根据业务处理错误、例如登录失效等处理接口返回错误码
    if (response.data.code !== 200) {
      if (meta.toast) {
        // 可以弹出错误toast
      }
      throw new Error('接口返回错误码，根据业务处理，可以弹出toast')
    }
    return response.data
  }
}

---

2. 注册插件（main.ts）

已经定义好全局请求配置和请求/响应拦截器，可以在main.ts 中注册：

import { createSSRApp } from 'vue'
import uViewPro, { httpPlugin } from 'uview-pro'
import { httpInterceptor, httpRequestConfig } from 'http.interceptor'

export function createApp() {
  const app = createSSRApp(App)

  // 注册uView-pro
  app.use(uViewPro)

  // 注册http插件
  app.use(httpPlugin, {
    interceptor: httpInterceptor,
    requestConfig: httpRequestConfig
  })

  return { app }
}

---

3. API 管理

建议将所有接口统一封装到 api/index.ts，便于维护和类型推断：

// api/index.ts
import { http } from 'uview-pro'

export const login = data => http.post('/api/login', data)
export const getUser = id => http.get('/api/user', { id })

页面中直接调用：

import { login, getUser } from '@/api'

const user = await getUser(1)

---

4. $u 工具库用法

需 import { $u } from 'uview-pro'

$u.http.get/post/put/delete 参数与 http 保持一致

import { $u } from 'uview-pro'

$u.http.get('/api/user', { id: 1 }, { meta: { toast: true } })
$u.http.post('/api/login', { username: 'xx' }, { meta: { loading: true } })

// 或
uni.$u.http.get('/api/user', { id: 1 }, { meta: { toast: true } })

进阶用法

多实例/多拦截器

import { Request } from 'uview-pro'

const customHttp = new Request()
customHttp.setConfig({ baseUrl: 'https://other.api.com' })
customHttp.interceptor.request = config => {
  // ...自定义逻辑
  return config
}
export { customHttp }

扩展 meta 字段

你可以在 meta 中扩展自定义参数，在拦截器中读取：

http.get('/api/user', {}, { meta: { toast: true, customFlag: true } })
// 在拦截器中：config.meta?.customFlag

结合 hooks 封装

// hooks/useApi.ts
import { http } from 'uview-pro'
export function useApi() {
  return {
    login: data => http.post('/api/login', data),
    getUser: id => http.get('/api/user', { id })
  }
}

类型提示与 TS 支持

• 所有请求方法均有完整类型推断
• 支持泛型：http.get<MyResType>(url)
• 支持自定义 Request/Response 类型
• 推荐在 api 层定义类型，页面调用自动推断

常见问题 FAQ

1. 如何全局配置 baseUrl、header、meta？

使用 http.setConfig({ ... })，建议在 main.ts 或拦截器注册前调用。

2. 如何单次请求自定义 toast/loading？

通过 meta 字段：http.post(url, data, { meta: { toast: true, loading: true } })

3. 如何自定义拦截器？

参考 http.interceptor.ts，request/response 可灵活扩展。

4. 如何在组合式 API 中优雅使用？

直接 import { http }，无需 getCurrentInstance。

5. 如何处理多环境/多 baseUrl？

可通过 setConfig 动态切换，或 new Request() 多实例。

6. 如何捕获和处理错误？

建议统一在 response 拦截器处理，页面可用 try/catch 或 .catch。

7. $u.http.get/post 与 http 有什么区别？

$u.http.get/post 适配 uview-pro 导出的 http，参数与 http 完全一致，底层同一实现。 即以下方式是同等的：

import { $u, http } from 'uview-pro'

// 方式一
http.get('/api/user', { id: 1 }, { meta: { toast: true } })

// 方式二
$u.http.get('/api/user', { id: 1 }, { meta: { toast: true } })

// 方式三
uni.$u.http.get('/api/user', { id: 1 }, { meta: { toast: true } })

8. put/delete 在小程序平台有限制吗？

put/delete 在支付宝、头条等部分平台有限制，详见最上方提示。

---