http

http 是 Oiyo 数据获取模块提供的默认请求实例，无前置配置，可直接发起请求。

http.create()

基于当前实例派生新实例，与 createHttp 派生出的实例共用同一套方法

声明

http.create(config: HttpConfig): Http

参数

config 的属性以及类型继承于 HttpCommonOptions：

钩子

config.onBeforeRequest()

触发时机：发出请求前

• 声明

  interface HttpConfig {
    onBeforeRequest(context: { url: HttpURL, options: HttpOptions }): MaybePromise<HttpOptions | void>
  }
  

• 示例

  const api = createHttp({
    onBeforeRequest({ url, options }) {
      console.log('发起请求', url, options)
    },
  })
  

config.onRequestError()

触发时机：没有 HTTP 响应 —— 传输失败（网络错误、超时、跨域等）通过 HttpError 抛出；若错误来自 onBeforeRequest 自身抛出的异常（或已中断信号），则原样透传

• 声明

  interface HttpConfig {
    onRequestError(context: { url: HttpURL, options: HttpOptions, error: Error }): MaybePromise<unknown>
  }
  

• 示例

  const api = createHttp({
    onRequestError({ error }) {
      console.error('请求失败', error)
    },
  })
  

config.onResponseSuccess()

触发时机：有响应且 validateStatus 通过（默认 2xx）

• 声明

  interface HttpConfig {
    onResponseSuccess(context: { url: HttpURL, options: HttpOptions, response: HttpRawResponse }): MaybePromise<HttpRawResponse | void>
  }
  

• 示例

  const api = createHttp({
    onResponseSuccess({ response }) {
      console.log('收到响应', response.statusCode)
    },
  })
  

config.onResponseError()

触发时机：有响应但 validateStatus 未通过（会 reject HttpError.STATUS）

• 声明

  interface HttpConfig {
    onResponseError(context: { url: HttpURL, options: HttpOptions, response: HttpRawResponse, error: HttpError }): MaybePromise<unknown>
  }
  

• 示例

  const api = createHttp({
    onResponseError({ response, error }) {
      console.error('响应错误', response.statusCode, error)
    },
  })
  

http.request()

普通请求方法

声明

http.request<TRBody = any>(url: HttpURL, options?: HttpRequestOptions): Promise<TRBody>

参数

options 的属性以及类型继承于 HttpCommonOptions：

回调

options.onChunk()

触发时机：每当收到一段流式数据（对应原生 task.onChunkReceived）

• 声明

  interface HttpRequestOptions {
    onChunk(event: { data: ArrayBuffer }, off: () => void): void
  }
  

• 示例

  await http.request('/chat/stream', {
    onChunk(event, off) {
      console.log('收到流式分片', event.data)
  
      // 不再需要监听时调用，关闭流式数据监听
      off()
    },
  })
  

http.upload()

文件上传，底层走 uni.uploadFile

声明

http.upload<TRBody = any>(url: HttpURL, options?: HttpUploadOptions): Promise<TRBody>

参数

options 的属性以及类型继承于 HttpCommonOptions：

回调

options.onProgress()

触发时机：上传进度变化时（对应原生 task.onProgressUpdate）

• 声明

  interface HttpUploadOptions {
    onProgress(data: UniAppUploadOnProgressData, off: () => void): void
  }
  
  interface UniAppUploadOnProgressData {
    /** 上传进度百分比 */
    progress: number
    /** 已经上传的数据长度，单位 Bytes */
    totalBytesSent: number
    /** 预期需要上传的数据总长度，单位 Bytes */
    totalBytesExpectedToSend: number
  }
  

• 示例

  await http.upload('/upload', {
    filePath,
    onProgress(data, off) {
      console.log(`上传进度 ${data.progress}%`)
  
      // 满足条件后可调用 off() 关闭上传进度监听
      if (data.progress >= 90) {
        off()
      }
    },
  })
  

http.download()

文件下载

声明

http.download<TRBody = any>(url: HttpURL, options?: HttpDownloadOptions): Promise<TRBody>

参数

options 的属性以及类型继承于 HttpCommonOptions：

回调

options.onProgress()

触发时机：下载进度变化时（对应原生 task.onProgressUpdate）

• 声明

  interface HttpDownloadOptions {
    onProgress(data: UniAppDownloadOnProgressData, off: () => void): void
  }
  
  interface UniAppDownloadOnProgressData {
    /** 下载进度百分比 */
    progress: number
    /** 已经下载的数据长度，单位 Bytes */
    totalBytesWritten: number
    /** 预期需要下载的数据总长度，单位 Bytes */
    totalBytesExpectedToWrite: number
  }
  

• 示例

  const { tempFilePath } = await http.download('/file/report.pdf', {
    onProgress(data, off) {
      console.log(`下载进度 ${data.progress}%`)
  
      // 满足条件后可调用 off() 关闭下载进度监听
      if (data.progress >= 50) {
        off()
      }
    },
  })
  

行为

• 无 baseURL，资源必须传绝对地址，相对地址会因缺省基础地址而报错。
• 无预置钩子与公共 headers，每次请求只走单次配置。
• 与 createHttp 派生出的实例共用同一套配置项、钩子、重试与中断能力。

相关