更新记录

1.0.4（2026-04-21） 下载此版本

uni-axios-http-adapter

基于 uni.request 的请求封装，支持：

• 请求实例创建
• 请求/响应拦截器
• GET、POST、PUT、DELETE 快捷方法
• 默认请求配置合并
• 请求中 loading 展示
• TypeScript 类型支持

适用于 uni-app 项目中统一管理接口请求逻辑。

安装

npm install uni-axios-http-adapter

快速开始

import axios from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: 'https://example.com',
  timeout: 10000,
  header: {
    Clientid: 'your-client-id'
  }
})

export default service

基本用法

发起 GET 请求

import service from '@/utils/request'

service.get({
  url: '/user/info',
  data: {
    id: 1
  }
}).then(res => {
  console.log(res)
}).catch(err => {
  console.log(err)
})

发起 POST 请求

import service from '@/utils/request'

service.post({
  url: '/user/login',
  data: {
    username: 'admin',
    password: '123456'
  }
}).then(res => {
  console.log(res)
})

发起 PUT 请求

service.put({
  url: '/user/update',
  data: {
    nickname: 'new-name'
  }
})

发起 DELETE 请求

service.del({
  url: '/user/1'
})

直接传入配置对象调用

service({
  url: '/article/list',
  method: 'GET',
  data: {
    pageNum: 1,
    pageSize: 10
  }
})

创建实例

推荐在项目中先创建自己的请求实例，再统一添加鉴权、错误处理、加密等逻辑。

import axios from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  },
  showLoading: true,
  loadingText: '请求中...',
  loadingTime: 800,
  loadingMask: true
})

export default service

请求配置

create 和单次请求都支持以下配置项。

实例配置 CreateAxios

单次请求配置 RequestAxios

在 CreateAxios 的基础上，额外支持：

拦截器

实例支持：

• service.interceptor.request.use()
• service.interceptor.response.use()

请求拦截器

请求拦截器常用于：

• 统一添加 token
• 动态追加请求头
• 请求参数加密
• 按业务设置自定义标记

import axios, { type InterceptorRequestAxios } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  }
})

service.interceptor.request.use((config: InterceptorRequestAxios) => {
  config.header = config.header || {}
  config.header.Authorization = 'Bearer ' + useUserStore().token
  return config
})

响应拦截器

响应拦截器常用于：

• 统一处理业务状态码
• 统一提示错误信息
• 处理未登录状态
• 对返回数据做二次转换

import axios, { type ResponseResult, type ResultError } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL
})

service.interceptor.response.use((res: ResponseResult) => {
  const resp = res.response

  if (resp.data.code === 200) {
    return resp.data
  }

  return Promise.reject(resp.data)
}, (error: ResultError) => {
  return Promise.reject(error.errMsg)
})

完整业务封装示例

下面是一份适合在项目中直接使用的二次封装示例，包含：

• token 注入
• 按请求头标记决定是否加密
• 统一处理 401
• 统一业务错误提示

import axios, { type InterceptorRequestAxios, type ResponseResult, type ResultError } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  }
})

service.interceptor.request.use((config: InterceptorRequestAxios) => {
  config.header = config.header || {}
  config.header.Authorization = 'Bearer ' + useUserStore().token

  return config
})

service.interceptor.response.use((res: ResponseResult) => {
  const resp = res.response

  if (resp.data.code === 401) {

    return Promise.reject(resp.data)
  }

  if (resp.data.code === 200) {
    return resp.data
  }

  return Promise.reject(resp.data)
}, (response: ResultError) => {
  return Promise.reject(response.errMsg)
})

export default service

自定义请求头标记

由于 header 类型是 Record<string, any>，你可以在项目中约定自己的业务字段，例如：

示例：

service.post({
  url: '/login',
  data: {
    username: 'admin',
    password: '123456'
  },
  header: {
    isEncrypt: true,
    notErrorToast: true
  }
})

返回值说明

请求成功

当网络请求成功且你在响应拦截器中 return resp.data 时，业务侧拿到的是后端返回的数据对象。

常见结构如下：

{
  code: 200,
  data: {},
  msg: 'success'
}

请求失败

以下情况通常会进入 catch：

• 网络异常
• 请求超时
• 非 200 状态码被拒绝
• 响应拦截器主动 Promise.reject()

service.get({ url: '/user/info' })
  .then(res => {
    console.log('success:', res)
  })
  .catch(err => {
    console.log('error:', err)
  })

默认配置

库内默认配置如下：

{
  baseURL: '', // 请求的根域名
  // 默认的请求头
  header: {},
  method: 'POST',
  // 设置为json，返回后uni.request会对数据进行一次JSON.parse
  dataType: 'json',
  // 此参数无需处理，因为5+和支付宝小程序不支持，默认为text即可
  responseType: 'text',
  showLoading: true, // 是否显示请求中的loading
  loadingText: '请求中...',
  loadingTime: 800, // 在此时间内，请求还没回来的话，就显示加载中动画，单位ms
  timer: undefined, // 定时器
  loadingMask: true, // 展示loading的时候，是否给一个透明的蒙层，防止触摸穿透
  timeout: 3000
}

注意事项

• header 字段名称使用的是 header，不是 headers
• 删除请求方法名为 del，不是 delete
• baseURL 会在请求地址不是完整 URL 时自动拼接
• 请求完成后会自动关闭 loading
• 业务加密、业务码判断、事件派发等逻辑需要你在拦截器中自行扩展

导出类型

当前库对外暴露以下类型：

• InterceptorRequestAxios
• ResponseResult
• ResultError

示例：

import axios, {
  type InterceptorRequestAxios,
  type ResponseResult,
  type ResultError
} from 'uni-axios-http-adapter'

平台兼容性

uni-app(3.7.6)

uni-axios-http-adapter

基于 uni.request 的请求封装，支持：

• 请求实例创建
• 请求/响应拦截器
• GET、POST、PUT、DELETE 快捷方法
• 默认请求配置合并
• 请求中 loading 展示
• TypeScript 类型支持

适用于 uni-app 项目中统一管理接口请求逻辑。

安装

npm install uni-axios-http-adapter

快速开始

import axios from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: 'https://example.com',
  timeout: 10000,
  header: {
    Clientid: 'your-client-id'
  }
})

export default service

基本用法

发起 GET 请求

import service from '@/utils/request'

service.get({
  url: '/user/info',
  data: {
    id: 1
  }
}).then(res => {
  console.log(res)
}).catch(err => {
  console.log(err)
})

发起 POST 请求

import service from '@/utils/request'

service.post({
  url: '/user/login',
  data: {
    username: 'admin',
    password: '123456'
  }
}).then(res => {
  console.log(res)
})

发起 PUT 请求

service.put({
  url: '/user/update',
  data: {
    nickname: 'new-name'
  }
})

发起 DELETE 请求

service.del({
  url: '/user/1'
})

直接传入配置对象调用

service({
  url: '/article/list',
  method: 'GET',
  data: {
    pageNum: 1,
    pageSize: 10
  }
})

创建实例

推荐在项目中先创建自己的请求实例，再统一添加鉴权、错误处理、加密等逻辑。

import axios from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  },
  showLoading: true,
  loadingText: '请求中...',
  loadingTime: 800,
  loadingMask: true
})

export default service

请求配置

create 和单次请求都支持以下配置项。

实例配置 CreateAxios

单次请求配置 RequestAxios

在 CreateAxios 的基础上，额外支持：

拦截器

实例支持：

• service.interceptor.request.use()
• service.interceptor.response.use()

请求拦截器

请求拦截器常用于：

• 统一添加 token
• 动态追加请求头
• 请求参数加密
• 按业务设置自定义标记

import axios, { type InterceptorRequestAxios } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  }
})

service.interceptor.request.use((config: InterceptorRequestAxios) => {
  config.header = config.header || {}
  config.header.Authorization = 'Bearer ' + useUserStore().token
  return config
})

响应拦截器

响应拦截器常用于：

• 统一处理业务状态码
• 统一提示错误信息
• 处理未登录状态
• 对返回数据做二次转换

import axios, { type ResponseResult, type ResultError } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL
})

service.interceptor.response.use((res: ResponseResult) => {
  const resp = res.response

  if (resp.data.code === 200) {
    return resp.data
  }

  return Promise.reject(resp.data)
}, (error: ResultError) => {
  return Promise.reject(error.errMsg)
})

完整业务封装示例

下面是一份适合在项目中直接使用的二次封装示例，包含：

• token 注入
• 按请求头标记决定是否加密
• 统一处理 401
• 统一业务错误提示

import axios, { type InterceptorRequestAxios, type ResponseResult, type ResultError } from 'uni-axios-http-adapter'

const service = axios.create({
  baseURL: import.meta.env.VITE_BASE_URL,
  timeout: 100000,
  header: {
    Clientid: import.meta.env.VITE_CLIENT_ID
  }
})

service.interceptor.request.use((config: InterceptorRequestAxios) => {
  config.header = config.header || {}
  config.header.Authorization = 'Bearer ' + useUserStore().token

  return config
})

service.interceptor.response.use((res: ResponseResult) => {
  const resp = res.response

  if (resp.data.code === 401) {

    return Promise.reject(resp.data)
  }

  if (resp.data.code === 200) {
    return resp.data
  }

  return Promise.reject(resp.data)
}, (response: ResultError) => {
  return Promise.reject(response.errMsg)
})

export default service

自定义请求头标记

由于 header 类型是 Record<string, any>，你可以在项目中约定自己的业务字段，例如：

示例：

service.post({
  url: '/login',
  data: {
    username: 'admin',
    password: '123456'
  },
  header: {
    isEncrypt: true,
    notErrorToast: true
  }
})

返回值说明

请求成功

当网络请求成功且你在响应拦截器中 return resp.data 时，业务侧拿到的是后端返回的数据对象。

常见结构如下：

{
  code: 200,
  data: {},
  msg: 'success'
}

请求失败

以下情况通常会进入 catch：

• 网络异常
• 请求超时
• 非 200 状态码被拒绝
• 响应拦截器主动 Promise.reject()

service.get({ url: '/user/info' })
  .then(res => {
    console.log('success:', res)
  })
  .catch(err => {
    console.log('error:', err)
  })

默认配置

库内默认配置如下：

{
  baseURL: '', // 请求的根域名
  // 默认的请求头
  header: {},
  method: 'POST',
  // 设置为json，返回后uni.request会对数据进行一次JSON.parse
  dataType: 'json',
  // 此参数无需处理，因为5+和支付宝小程序不支持，默认为text即可
  responseType: 'text',
  showLoading: true, // 是否显示请求中的loading
  loadingText: '请求中...',
  loadingTime: 800, // 在此时间内，请求还没回来的话，就显示加载中动画，单位ms
  timer: undefined, // 定时器
  loadingMask: true, // 展示loading的时候，是否给一个透明的蒙层，防止触摸穿透
  timeout: 3000
}

注意事项

• header 字段名称使用的是 header，不是 headers
• 删除请求方法名为 del，不是 delete
• baseURL 会在请求地址不是完整 URL 时自动拼接
• 请求完成后会自动关闭 loading
• 业务加密、业务码判断、事件派发等逻辑需要你在拦截器中自行扩展

导出类型

当前库对外暴露以下类型：

• InterceptorRequestAxios
• ResponseResult
• ResultError

示例：

import axios, {
  type InterceptorRequestAxios,
  type ResponseResult,
  type ResultError
} from 'uni-axios-http-adapter'