---
name: "request"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.0.1" }
  - { name: "@ray-js/ray", version: "0.3.23" }
platform:
  - "iOS"
  - "Android"
async: true
title: "request - 发起 HTTPS 网络请求"
---

## request

> [VERSION] BaseKit >= 2.0.1 | @ray-js/ray >= 0.3.23

> [PLATFORM] iOS, Android

> ⚡ **支持 Promise 调用** — 不传 success / fail / complete 回调时，该方法返回 Promise。

### 描述

发起 HTTPS 网络请求

### 参数

| 属性 | 类型 | 必填 | 默认值 | 最低版本 | 描述 |
| --- | --- | --- | --- | --- | --- |
| `url` | `string` | 是 | - | `2.0.1` | 开发者服务器接口地址 |
| `data` | `string` | 否 | - | `2.0.1` | 请求的参数 |
| `header` | `Record<string, string>` | 否 | - | `2.0.1` | 设置请求的 header，header 中不能设置 Referer。content-type 默认为 application/json |
| `timeout` | `number` | 否 | - | `2.0.1` | 超时时间，单位为毫秒 |
| `method` | `"OPTIONS" \| "GET" \| "HEAD" \| "POST" \| "PUT" \| "DELETE" \| "TRACE" \| "CONNECT"` | 否 | `'GET'` | `2.0.1` | HTTP 请求方法 |
| `dataType` | `string` | 否 | `"json"` | `2.0.1` | 请求体里的数据类型（仅Android，且请求方式不为GET时生效） |
| `responseType` | `string` | 否 | `"text"` | `2.0.1` | 返回的数据类型 |
| `enableHttp2` | `boolean` | 否 | `false` | `2.0.1` | enableHttp2 |
| `enableQuic` | `boolean` | 否 | `false` | `2.0.1` | enableQuic |
| `enableCache` | `boolean` | 否 | `false` | `2.0.1` | enableCache |
| `complete` | `() => void` | 否 | - | - | 接口调用结束的回调函数（调用成功、失败都会执行） |
| `success` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用成功的回调函数 |
| `fail` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用失败的回调函数 |

#### success 回调参数

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `data` | `string` | `3.2.6` | 开发者服务器返回的数据 |
| `statusCode` | `number` | `3.2.6` | 开发者服务器返回的 HTTP 状态码 |
| `header` | `Record<string, string>` | `3.2.6` | 开发者服务器返回的 HTTP Response Header |
| `cookies` | `string[]` | `3.2.6` | 开发者服务器返回的 cookies，格式为字符串数组 |
| `profile` | `Profile` | `3.2.6` | 网络请求过程中一些调试信息 |
| `taskId` | `string` | `3.2.6` | 网络请求id，用户取消、监听等操作 |

#### fail 回调参数

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorMsg` | `string` | 错误信息 |
| `errorCode` | `string \| number` | 错误码 |
| `innerError` | `Object` | 错误扩展 |

##### fail(params).innerError 的属性

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorCode` | `string \| number` | 错误扩展码 |
| `errorMsg` | `string` | 错误扩展信息 |


### 引用对象

##### `interface` Profile

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `redirectStart` | `number` | `3.2.6` | 第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算，否则值为 0 |
| `redirectEnd` | `number` | `3.2.6` | 最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算，否则值为 0 |
| `fetchStart` | `number` | `3.2.6` | 组件准备好使用 HTTP 请求抓取资源的时间，这发生在检查本地缓存之前 |
| `domainLookupStart` | `number` | `3.2.6` | DNS 域名查询开始的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 |
| `domainLookupEnd` | `number` | `3.2.6` | DNS 域名查询完成的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 |
| `connectStart` | `number` | `3.2.6` | HTTP（TCP） 开始建立连接的时间，如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接开始的时间 |
| `connectEnd` | `number` | `3.2.6` | HTTP（TCP） 完成建立连接的时间（完成握手），如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接完成的时间。注意这里握手结束，包括安全连接建立完成、SOCKS 授权通过 |
| `SSLconnectionStart` | `number` | `3.2.6` | SSL建立连接的时间,如果不是安全连接,则值为 0 |
| `SSLconnectionEnd` | `number` | `3.2.6` | SSL建立完成的时间,如果不是安全连接,则值为 0 |
| `requestStart` | `number` | `3.2.6` | HTTP请求读取真实文档开始的时间（完成建立连接），包括从本地读取缓存。连接错误重连时，这里显示的也是新建立连接的时间 |
| `requestEnd` | `number` | `3.2.6` | HTTP请求读取真实文档结束的时间 |
| `responseStart` | `number` | `3.2.6` | HTTP 开始接收响应的时间（获取到第一个字节），包括从本地读取缓存 |
| `responseEnd` | `number` | `3.2.6` | HTTP 响应全部接收完成的时间（获取到最后一个字节），包括从本地读取缓存 |
| `rtt` | `number` | `3.2.6` | 当次请求连接过程中实时 rtt |
| `estimate_nettype` | `string` | `3.2.6` | 评估的网络状态 slow 2g/2g/3g/4g |
| `httpRttEstimate` | `number` | `3.2.6` | 协议层根据多个请求评估当前网络的 rtt（仅供参考） |
| `transportRttEstimate` | `number` | `3.2.6` | 传输层根据多个请求评估的当前网络的 rtt（仅供参考） |
| `downstreamThroughputKbpsEstimate` | `number` | `3.2.6` | 评估当前网络下载的kbps |
| `throughputKbps` | `number` | `3.2.6` | 当前网络的实际下载kbps |
| `peerIP` | `string` | `3.2.6` | 当前请求的IP |
| `port` | `number` | `3.2.6` | 当前请求的端口 |
| `socketReused` | `boolean` | `3.2.6` | 是否复用连接 |
| `sendBytesCount` | `number` | `3.2.6` | 发送的字节数 |
| `receivedBytedCount` | `number` | `3.2.6` | 收到字节数 |


### 合法值

##### `method` 合法值

| 值 | 说明 |
| --- | --- |
| `"OPTIONS"` | HTTP 请求 OPTIONS |
| `"GET"` | HTTP 请求 GET |
| `"HEAD"` | HTTP 请求 HEAD |
| `"POST"` | HTTP 请求 POST |
| `"PUT"` | HTTP 请求 PUT |
| `"DELETE"` | HTTP 请求 DELETE |
| `"TRACE"` | HTTP 请求 TRACE |
| `"CONNECT"` | HTTP 请求 TRACE |


### 示例代码

#### Demo

```tsx
import { request } from '@ray-js/ray'

// 发起 HTTPS GET 请求。ty.request 同步返回一个 RequestTask 对象，请求结果通过 success/fail 回调返回。
request({
  url: "https://httpbin.org/get",
  method: "GET",
  success: data => {
    console.log(data);
  },
  fail: error => {
    console.error(error);
  },
});
```