uniApp 请求封装与错误处理

多端项目的请求层如果不统一,最终会在每个页面里出现一套自己的 loading、错误提示与重试逻辑。

为什么需要封装

直接调用 uni.request 会遇到:

  • 每个页面重复写 header、baseURL、超时
  • 错误码处理散落各处
  • 登录失效无法统一跳转
  • loading 状态与业务状态耦合

基础封装

type RequestOptions = {
  url: string
  method?: 'GET' | 'POST'
  data?: Record<string, unknown>
  header?: Record<string, string>
}

export function request<T>(options: RequestOptions): Promise<T> {
  return new Promise((resolve, reject) => {
    uni.request({
      url: `${BASE_URL}${options.url}`,
      method: options.method ?? 'GET',
      data: options.data,
      header: {
        'Content-Type': 'application/json',
        ...options.header
      },
      timeout: 10000,
      success: (res) => {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data as T)
          return
        }
        reject(new Error(`HTTP ${res.statusCode}`))
      },
      fail: (error) => reject(new Error(error.errMsg || '网络异常'))
    })
  })
}

统一错误处理

把「网络层错误」和「业务层错误」分开:

async function loadPosts() {
  try {
    const data = await request<{ list: Post[] }>({ url: '/posts' })
    return data.list
  } catch (error) {
    const message = error instanceof Error ? error.message : '加载失败'
    uni.showToast({ title: message, icon: 'none' })
    return []
  }
}

登录态与拦截

在请求头统一注入 token,并处理 401:

header: {
  Authorization: `Bearer ${uni.getStorageSync('token') ?? ''}`
}

遇到 401 时清除本地登录态并跳转登录页,不要在业务组件里各自处理。

取消与并发

  • 页面卸载时取消未完成请求,避免更新已销毁的组件
  • 列表页并发加载多个接口时,用 Promise.allSettled 保证部分失败不影响整体
  • 搜索场景使用防抖,减少无效请求

实践建议

  1. 请求层只负责传输与统一错误,不掺入业务判断
  2. 接口按业务域拆分文件,例如 api/post.ts、api/user.ts
  3. 类型定义与接口返回值保持一致
  4. 所有用户可见错误都要有提示与恢复路径
  5. 记录关键请求耗时,便于排查弱网问题