http

默认请求实例

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

oiyo 已将该 http 默认导入，无需再 import 即可直接使用。

http.create()

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

声明

http.create(config: HttpConfig): Http

参数

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

属性	类型	默认值	说明
`onRequest`	`function`	-	发起请求前的钩子
`onRequestError`	`function`	-	请求发起失败的钩子
`onResponse`	`function`	-	收到响应后的钩子
`onResponseError`	`function`	-	响应非 2xx 的钩子

属性	类型	默认值	说明
`baseURL`	`string`	-	基础地址，资源为绝对地址时忽略
`method`	`'GET' \| 'POST' \| ...`	随方法而定	请求方法
`headers`	`Record<string, string>`	-	请求头，多层配置浅合并
`query`	`Record<string, any>`	-	查询参数，会序列化拼接到 URL，支持数组
`body`	`any`	-	请求体（upload 时对应 formData）
`timeout`	`number`	-	超时时间（毫秒）
`raw`	`boolean`	`false`	为 `true` 返回完整响应对象，否则只返回精炼后的 `data`
`responseType`	`'json' \| 'text' \| 'arrayBuffer'`	`'json'`	响应体类型（手动解析）
`parseResponse`	`(text: string) => any`	-	自定义 JSON 解析函数
`retry`	`number \| false`	随方法而定	最大重试次数，`false` 不重试
`retryDelay`	`number`	-	重试间隔（毫秒）
`retryStatusCodes`	`number[]`	`[408, 409, 425, 429, 500, 502, 503, 504]`	参与重试的状态码
`ignoreResponseError`	`boolean`	`false`	为 `true` 时非 2xx 响应不抛错
`signal`	`HttpAbortSignal`	-	中断信号，由 `createHttpAborter()` 创建
`onHeadersReceived`	`(result) => void`	-	监听响应头

钩子

config.onRequest()

钩子触发时机：发起请求前

声明

interface HttpConfig {
  onRequest(context: { resource: HttpURL, options: HttpOptions }): MaybePromise<void>>
}

示例

const api = createHttp({
  onRequest({ resource, options }) {
    console.log('向该资源发起请求：', resource)
  },
})

config.onRequestError()

触发时机：请求发起失败

声明

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

示例

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

config.onResponse()

触发时机：收到响应后

声明

interface HttpConfig {
  onResponse(context: { resource: HttpURL, options: HttpOptions, response: HttpRawResponse }): MaybePromise<void>>
}

示例

const api = createHttp({
  onRequestError({ resource, options, response }) {
    console.log('收到响应', response.statusCode, response.data)
  },
})

config.onResponseError()

触发时机：响应非 2xx 的钩子

声明

interface HttpConfig {
  onResponseError(context: { resource: HttpURL, options: HttpOptions, response: HttpRawResponse }): MaybePromise<void>>
}

示例

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

钩子可声明在任意一层配置（实例、派生实例、单次请求）上。多层配置的同名钩子会在配置合并阶段串联为一个函数，按层级顺序依次执行。

http.request()

普通请求方法

声明

http.request(options: HttpRequestOptions): Http

参数

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

属性	类型	默认值	说明
`onChunk`	`function`	-	流式数据监听

属性	类型	默认值	说明
`baseURL`	`string`	-	基础地址，资源为绝对地址时忽略
`method`	`'GET' \| 'POST' \| ...`	随方法而定	请求方法
`headers`	`Record<string, string>`	-	请求头，多层配置浅合并
`query`	`Record<string, any>`	-	查询参数，会序列化拼接到 URL，支持数组
`body`	`any`	-	请求体（upload 时对应 formData）
`timeout`	`number`	-	超时时间（毫秒）
`raw`	`boolean`	`false`	为 `true` 返回完整响应对象，否则只返回精炼后的 `data`
`responseType`	`'json' \| 'text' \| 'arrayBuffer'`	`'json'`	响应体类型（手动解析）
`parseResponse`	`(text: string) => any`	-	自定义 JSON 解析函数
`retry`	`number \| false`	随方法而定	最大重试次数，`false` 不重试
`retryDelay`	`number`	-	重试间隔（毫秒）
`retryStatusCodes`	`number[]`	`[408, 409, 425, 429, 500, 502, 503, 504]`	参与重试的状态码
`ignoreResponseError`	`boolean`	`false`	为 `true` 时非 2xx 响应不抛错
`signal`	`HttpAbortSignal`	-	中断信号，由 `createHttpAborter()` 创建
`onHeadersReceived`	`(result) => void`	-	监听响应头

http.upload()

文件上传

声明

http.upload(options: HttpUploadOptions): Http

参数

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

属性	类型	默认值	说明
`name`	`string`	-	用于给服务端识别的名称
`method`	`POST`	`POST`	请求方法
`onProgress`	`function`	-	上传进度监听

属性	类型	默认值	说明
`baseURL`	`string`	-	基础地址，资源为绝对地址时忽略
`method`	`'GET' \| 'POST' \| ...`	随方法而定	请求方法
`headers`	`Record<string, string>`	-	请求头，多层配置浅合并
`query`	`Record<string, any>`	-	查询参数，会序列化拼接到 URL，支持数组
`body`	`any`	-	请求体（upload 时对应 formData）
`timeout`	`number`	-	超时时间（毫秒）
`raw`	`boolean`	`false`	为 `true` 返回完整响应对象，否则只返回精炼后的 `data`
`responseType`	`'json' \| 'text' \| 'arrayBuffer'`	`'json'`	响应体类型（手动解析）
`parseResponse`	`(text: string) => any`	-	自定义 JSON 解析函数
`retry`	`number \| false`	随方法而定	最大重试次数，`false` 不重试
`retryDelay`	`number`	-	重试间隔（毫秒）
`retryStatusCodes`	`number[]`	`[408, 409, 425, 429, 500, 502, 503, 504]`	参与重试的状态码
`ignoreResponseError`	`boolean`	`false`	为 `true` 时非 2xx 响应不抛错
`signal`	`HttpAbortSignal`	-	中断信号，由 `createHttpAborter()` 创建
`onHeadersReceived`	`(result) => void`	-	监听响应头

http.download()

文件下载

声明

http.download(options: HttpDownloadOptions): Http

参数

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

属性	类型	默认值	说明
`method`	`GET`	`GET`	请求方法
`onProgress`	`function`	-	下载进度监听

属性	类型	默认值	说明
`baseURL`	`string`	-	基础地址，资源为绝对地址时忽略
`method`	`'GET' \| 'POST' \| ...`	随方法而定	请求方法
`headers`	`Record<string, string>`	-	请求头，多层配置浅合并
`query`	`Record<string, any>`	-	查询参数，会序列化拼接到 URL，支持数组
`body`	`any`	-	请求体（upload 时对应 formData）
`timeout`	`number`	-	超时时间（毫秒）
`raw`	`boolean`	`false`	为 `true` 返回完整响应对象，否则只返回精炼后的 `data`
`responseType`	`'json' \| 'text' \| 'arrayBuffer'`	`'json'`	响应体类型（手动解析）
`parseResponse`	`(text: string) => any`	-	自定义 JSON 解析函数
`retry`	`number \| false`	随方法而定	最大重试次数，`false` 不重试
`retryDelay`	`number`	-	重试间隔（毫秒）
`retryStatusCodes`	`number[]`	`[408, 409, 425, 429, 500, 502, 503, 504]`	参与重试的状态码
`ignoreResponseError`	`boolean`	`false`	为 `true` 时非 2xx 响应不抛错
`signal`	`HttpAbortSignal`	-	中断信号，由 `createHttpAborter()` 创建
`onHeadersReceived`	`(result) => void`	-	监听响应头

行为

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

如需 baseURL、公共 headers、拦截 hooks 等团队约定，请使用 createHttp 创建实例。