# [RequestTask](/miniprogram/dev/api/network/request/RequestTask) wx.request(Object object)

> __以 [Promise 风格](/miniprogram/dev/framework/app-service/api.md#异步-API-返回-Promise) 调用__：不支持
> 
> __小程序插件__：支持，需要小程序基础库版本不低于 [1.9.6](1003706)
> 
> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

> 相关文档: [网络使用说明](/miniprogram/dev/framework/ability/network.md)、[局域网通信](/miniprogram/dev/framework/ability/mDNS.md)、[移动解析HttpDNS](/miniprogram/dev/framework/ability/HTTPDNS.md)

## 功能描述

发起 HTTPS 网络请求。使用前请注意阅读[相关说明](/miniprogram/dev/framework/ability/network.md)。

## 参数

### Object object


```json
[
  {
    "属性": "url",
    "类型": "string",
    "默认值": "",
    "必填": "是",
    "说明": "开发者服务器接口地址",
    "最低版本": ""
  },
  {
    "属性": "data",
    "类型": "string/object/ArrayBuffer",
    "默认值": "",
    "必填": "否",
    "说明": "请求的参数",
    "最低版本": ""
  },
  {
    "属性": "header",
    "类型": "Object",
    "默认值": "",
    "必填": "否",
    "说明": "设置请求的 header，header 中不能设置 Referer。\n\u0000INLINECODE_0\u0000 默认为 \u0000INLINECODE_1\u0000",
    "最低版本": ""
  },
  {
    "属性": "timeout",
    "类型": "number",
    "默认值": "",
    "必填": "否",
    "说明": "超时时间，单位为毫秒。默认值为 60000",
    "最低版本": "[2.10.0](1003706)"
  },
  {
    "属性": "method",
    "类型": "string",
    "默认值": "GET",
    "必填": "否",
    "说明": "HTTP 请求方法",
    "最低版本": "",
    "子项": [
      {
        "合法值": "OPTIONS",
        "说明": "HTTP 请求 OPTIONS"
      },
      {
        "合法值": "GET",
        "说明": "HTTP 请求 GET"
      },
      {
        "合法值": "HEAD",
        "说明": "HTTP 请求 HEAD"
      },
      {
        "合法值": "POST",
        "说明": "HTTP 请求 POST"
      },
      {
        "合法值": "PUT",
        "说明": "HTTP 请求 PUT"
      },
      {
        "合法值": "DELETE",
        "说明": "HTTP 请求 DELETE"
      },
      {
        "合法值": "TRACE",
        "说明": "HTTP 请求 TRACE"
      },
      {
        "合法值": "CONNECT",
        "说明": "HTTP 请求 CONNECT"
      }
    ]
  },
  {
    "属性": "dataType",
    "类型": "string",
    "默认值": "json",
    "必填": "否",
    "说明": "返回的数据格式。值为 \u0000INLINECODE_2\u0000 时，返回的数据为 JSON，返回后会对返回的数据进行一次 \u0000INLINECODE_3\u0000；其他值则不对返回的内容进行 \u0000INLINECODE_4\u0000",
    "最低版本": ""
  },
  {
    "属性": "responseType",
    "类型": "string",
    "默认值": "text",
    "必填": "否",
    "说明": "响应的数据类型",
    "最低版本": "[1.7.0](1003706)",
    "子项": [
      {
        "合法值": "text",
        "说明": "响应的数据为文本"
      },
      {
        "合法值": "arraybuffer",
        "说明": "响应的数据为 ArrayBuffer"
      }
    ]
  },
  {
    "属性": "useHighPerformanceMode",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "使用高性能模式。从基础库 v3.5.0 开始在 Android 端默认开启，其他端暂不生效。该模式下有更优的网络性能表现，更多信息请查看下方说明。",
    "最低版本": "[3.3.3](1003706)"
  },
  {
    "属性": "enableHttp2",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "开启 http2",
    "最低版本": "[2.10.4](1003706)"
  },
  {
    "属性": "enableProfile",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "是否开启 profile。iOS 和 Android 端默认开启，其他端暂不支持。开启后可在接口回调的 res.profile 中查看性能调试信息。",
    "最低版本": ""
  },
  {
    "属性": "enableQuic",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否开启 Quic/h3 协议（iOS 微信目前使用 gQUIC-Q43；Android 微信在 v8.0.54 前使用 gQUIC-Q43，v8.0.54 开始使用 IETF QUIC，即 h3 协议；PC微信使用 IETF QUIC，即 h3 协议）",
    "最低版本": "[2.10.4](1003706)"
  },
  {
    "属性": "enableCache",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "开启 Http 缓存",
    "最低版本": "[2.10.4](1003706)"
  },
  {
    "属性": "enableHttpDNS",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否开启 HttpDNS 服务。如开启，需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见 [移动解析HttpDNS](/miniprogram/dev/framework/ability/HTTPDNS.md)",
    "最低版本": "[2.19.1](1003706)"
  },
  {
    "属性": "httpDNSServiceId",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "HttpDNS 服务商 Id。 HttpDNS 用法详见 [移动解析HttpDNS](/miniprogram/dev/framework/ability/HTTPDNS.md)",
    "最低版本": "[2.19.1](1003706)"
  },
  {
    "属性": "httpDNSTimeout",
    "类型": "number",
    "默认值": "10000",
    "必填": "否",
    "说明": "HttpDNS 超时时间。HttpDNS解析时间超过该值时不再走HttpDNS，本次请求将回退到localDNS。默认为 10000 毫秒。 HttpDNS 用法详见 [移动解析HttpDNS](/miniprogram/dev/framework/ability/HTTPDNS.md)",
    "最低版本": "[3.8.9](1003706)"
  },
  {
    "属性": "enableHttpDNSFallback",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "是否开启 HttpDNS 兜底。开启时，HttpDNS 服务查询失败会回退到 localDNS；关闭时，HttpDNS 服务查询失败将直接报错，不回退到 localDNS。默认为 true。 HttpDNS 用法详见 [移动解析HttpDNS](/miniprogram/dev/framework/ability/HTTPDNS.md)",
    "最低版本": "[3.16.2](1003706)"
  },
  {
    "属性": "enableChunked",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "开启 transfer-encoding chunked。",
    "最低版本": "[2.20.2](1003706)"
  },
  {
    "属性": "forceCellularNetwork",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "强制使用蜂窝网络发送请求",
    "最低版本": "[2.21.0](1003706)"
  },
  {
    "属性": "redirect",
    "类型": "string",
    "默认值": "follow",
    "必填": "否",
    "说明": "重定向拦截策略。（目前安卓、iOS、开发者工具已支持，PC端将在后续支持）",
    "最低版本": "[3.2.2](1003706)",
    "子项": [
      {
        "合法值": "follow",
        "说明": "不拦截重定向，即客户端自动处理重定向"
      },
      {
        "合法值": "manual",
        "说明": "拦截重定向。开启后，当 http 状态码为 3xx 时客户端不再自动重定向，而是触发 onHeadersReceived 回调，并结束本次 request 请求。可通过 onHeadersReceived 回调中的 header.Location 获取重定向的 url"
      }
    ]
  },
  {
    "属性": "success",
    "类型": "function",
    "默认值": "",
    "必填": "否",
    "说明": "接口调用成功的回调函数",
    "最低版本": ""
  },
  {
    "属性": "fail",
    "类型": "function",
    "默认值": "",
    "必填": "否",
    "说明": "接口调用失败的回调函数",
    "最低版本": ""
  },
  {
    "属性": "complete",
    "类型": "function",
    "默认值": "",
    "必填": "否",
    "说明": "接口调用结束的回调函数（调用成功、失败都会执行）",
    "最低版本": ""
  }
]
```

#### object.success 回调函数
##### 参数

###### Object res


```json
[
  {
    "属性": "data",
    "类型": "string/Object/Arraybuffer",
    "说明": "开发者服务器返回的数据",
    "最低版本": ""
  },
  {
    "属性": "statusCode",
    "类型": "number",
    "说明": "开发者服务器返回的 HTTP 状态码",
    "最低版本": ""
  },
  {
    "属性": "header",
    "类型": "Object",
    "说明": "开发者服务器返回的 HTTP Response Header",
    "最低版本": "[1.2.0](1003706)"
  },
  {
    "属性": "cookies",
    "类型": "Array.<string>",
    "说明": "开发者服务器返回的 cookies，格式为字符串数组",
    "最低版本": "[2.10.0](1003706)"
  },
  {
    "属性": "profile",
    "类型": "Object",
    "说明": "网络请求过程中一些调试信息，[查看详细说明](/miniprogram/dev/framework/performance/network.html)。目前仅 iOS 和 Android 端支持，其他端暂不支持。",
    "最低版本": "[2.10.4](1003706)",
    "子项": [
      {
        "结构属性": "invokeStart",
        "类型": "number",
        "说明": "调用接口的时间。",
        "最低版本": "[3.8.10](1003706)"
      },
      {
        "结构属性": "httpDNSDomainLookUpStart",
        "类型": "number",
        "说明": "httpDNS 开始查询的时间。仅当开启 httpDNS 功能时返回该字段。目前仅wx.request接口支持",
        "最低版本": "[3.8.9](1003706)"
      },
      {
        "结构属性": "httpDNSDomainLookUpEnd",
        "类型": "number",
        "说明": "httpDNS 完成查询的时间。仅当开启 httpDNS 功能时返回该字段。目前仅wx.request接口支持",
        "最低版本": "[3.8.9](1003706)"
      },
      {
        "结构属性": "queueStart",
        "类型": "number",
        "说明": "开始排队的时间。达到并行上限时才需要排队。",
        "最低版本": "[3.8.10](1003706)"
      },
      {
        "结构属性": "queueEnd",
        "类型": "number",
        "说明": "结束排队的时间。达到并行上限时才需要排队。如果未发生排队，则该字段和 queueStart 字段值相同",
        "最低版本": "[3.8.10](1003706)"
      },
      {
        "结构属性": "redirectStart",
        "类型": "number",
        "说明": "第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算，否则值为 0",
        "最低版本": ""
      },
      {
        "结构属性": "redirectEnd",
        "类型": "number",
        "说明": "最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算，否则值为 0",
        "最低版本": ""
      },
      {
        "结构属性": "fetchStart",
        "类型": "number",
        "说明": "组件准备好使用 HTTP 请求抓取资源的时间，这发生在检查本地缓存之前",
        "最低版本": ""
      },
      {
        "结构属性": "domainLookUpStart",
        "类型": "number",
        "说明": "Local DNS 域名查询开始的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等",
        "最低版本": ""
      },
      {
        "结构属性": "domainLookUpEnd",
        "类型": "number",
        "说明": "Local DNS 域名查询完成的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等",
        "最低版本": ""
      },
      {
        "结构属性": "connectStart",
        "类型": "number",
        "说明": "HTTP（TCP） 开始建立连接的时间，如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接开始的时间",
        "最低版本": ""
      },
      {
        "结构属性": "connectEnd",
        "类型": "number",
        "说明": "HTTP（TCP） 完成建立连接的时间（完成握手），如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接完成的时间。注意这里握手结束，包括安全连接建立完成、SOCKS 授权通过",
        "最低版本": ""
      },
      {
        "结构属性": "SSLconnectionStart",
        "类型": "number",
        "说明": "SSL建立连接的时间,如果不是安全连接,则值为 0",
        "最低版本": ""
      },
      {
        "结构属性": "SSLconnectionEnd",
        "类型": "number",
        "说明": "SSL建立完成的时间,如果不是安全连接,则值为 0",
        "最低版本": ""
      },
      {
        "结构属性": "requestStart",
        "类型": "number",
        "说明": "HTTP请求读取真实文档开始的时间（完成建立连接），包括从本地读取缓存。连接错误重连时，这里显示的也是新建立连接的时间",
        "最低版本": ""
      },
      {
        "结构属性": "requestEnd",
        "类型": "number",
        "说明": "HTTP请求读取真实文档结束的时间",
        "最低版本": ""
      },
      {
        "结构属性": "responseStart",
        "类型": "number",
        "说明": "HTTP 开始接收响应的时间（获取到第一个字节），包括从本地读取缓存",
        "最低版本": ""
      },
      {
        "结构属性": "responseEnd",
        "类型": "number",
        "说明": "HTTP 响应全部接收完成的时间（获取到最后一个字节），包括从本地读取缓存",
        "最低版本": ""
      },
      {
        "结构属性": "rtt",
        "类型": "number",
        "说明": "当次请求连接过程中实时 rtt",
        "最低版本": ""
      },
      {
        "结构属性": "estimate_nettype",
        "类型": "number",
        "说明": "评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 6",
        "最低版本": ""
      },
      {
        "结构属性": "httpRttEstimate",
        "类型": "number",
        "说明": "协议层根据多个请求评估当前网络的 rtt（仅供参考）",
        "最低版本": ""
      },
      {
        "结构属性": "transportRttEstimate",
        "类型": "number",
        "说明": "传输层根据多个请求评估的当前网络的 rtt（仅供参考）",
        "最低版本": ""
      },
      {
        "结构属性": "downstreamThroughputKbpsEstimate",
        "类型": "number",
        "说明": "评估当前网络下载的kbps",
        "最低版本": ""
      },
      {
        "结构属性": "throughputKbps",
        "类型": "number",
        "说明": "当前网络的实际下载kbps",
        "最低版本": ""
      },
      {
        "结构属性": "peerIP",
        "类型": "string",
        "说明": "当前请求的IP",
        "最低版本": ""
      },
      {
        "结构属性": "port",
        "类型": "number",
        "说明": "当前请求的端口",
        "最低版本": ""
      },
      {
        "结构属性": "socketReused",
        "类型": "boolean",
        "说明": "是否复用连接",
        "最低版本": ""
      },
      {
        "结构属性": "sendBytesCount",
        "类型": "number",
        "说明": "发送的字节数",
        "最低版本": ""
      },
      {
        "结构属性": "receivedBytedCount",
        "类型": "number",
        "说明": "收到字节数",
        "最低版本": ""
      },
      {
        "结构属性": "protocol",
        "类型": "string",
        "说明": "使用协议类型，有效值：http1.1, h2, quic, unknown",
        "最低版本": ""
      },
      {
        "结构属性": "usingHighPerformanceMode",
        "类型": "boolean",
        "说明": "是否走到了高性能模式。基础库 v3.3.4 起支持。",
        "最低版本": ""
      }
    ]
  },
  {
    "属性": "exception",
    "类型": "Object",
    "说明": "网络请求过程中的一些异常信息，例如httpdns超时等",
    "最低版本": "[3.0.0](1003706)",
    "子项": [
      {
        "结构属性": "retryCount",
        "类型": "number",
        "说明": "本次请求底层重试次数"
      },
      {
        "结构属性": "reasons",
        "类型": "Array.<Object>",
        "说明": "本次请求底层失败信息，所有失败信息均符合Errno错误码",
        "子项": [
          {
            "结构属性": "errMsg",
            "类型": "string",
            "说明": "错误原因"
          },
          {
            "结构属性": "errno",
            "类型": "string",
            "说明": "错误码"
          }
        ]
      }
    ]
  },
  {
    "属性": "useHttpDNS",
    "类型": "boolean",
    "说明": "最终请求是否使用了HttpDNS解析的IP。仅当enableHttpDNS传true时返回此字段。如果开启enableHttpDNS但最终请求未使用HttpDNS解析的IP，可在exception查看原因。",
    "最低版本": "[3.4.10](1003706)"
  }
]
```

#### object.fail 回调函数
##### 参数

###### Object err


```json
[
  {
    "属性": "errMsg",
    "类型": "String",
    "说明": "错误信息",
    "最低版本": ""
  },
  {
    "属性": "errno",
    "类型": "Number",
    "说明": "errno 错误码，错误码的详细说明参考 [Errno错误码](/miniprogram/dev/framework/usability/PublicErrno.md)",
    "最低版本": "[2.24.0](1003706)"
  },
  {
    "属性": "exception",
    "类型": "Object",
    "说明": "网络请求过程中的一些异常信息，例如httpdns超时等",
    "最低版本": "[3.8.10](1003706)",
    "子项": [
      {
        "结构属性": "retryCount",
        "类型": "number",
        "说明": "本次请求底层重试次数"
      },
      {
        "结构属性": "reasons",
        "类型": "Array.<Object>",
        "说明": "本次请求底层失败信息，所有失败信息均符合Errno错误码",
        "子项": [
          {
            "结构属性": "errMsg",
            "类型": "string",
            "说明": "错误原因"
          },
          {
            "结构属性": "errno",
            "类型": "string",
            "说明": "错误码"
          }
        ]
      }
    ]
  },
  {
    "属性": "useHttpDNS",
    "类型": "boolean",
    "说明": "最终请求是否使用了HttpDNS解析的IP。仅当enableHttpDNS传true时返回此字段。如果开启enableHttpDNS但最终请求未使用HttpDNS解析的IP，可在exception查看原因。",
    "最低版本": "[3.8.10](1003706)"
  }
]
```

## 返回值

### [RequestTask](/miniprogram/dev/api/network/request/RequestTask)

> 基础库 1.4.0 开始支持，低版本需做[兼容处理](1003706)。

请求任务对象

## data 参数说明

最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String 。转换规则如下：
- 对于 `GET` 方法的数据，会将数据转换成 query string（`encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...`）
- 对于 `POST` 方法且 `header['content-type']` 为 `application/json` 的数据，会对数据进行 JSON 序列化
- 对于 `POST` 方法且 `header['content-type']` 为 `application/x-www-form-urlencoded` 的数据，会将数据转换成 query string `（encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...）`

## useHighPerformanceMode 高性能模式说明

在该模式下，框架将会采用全新的网络请求模块，默认支持 HTTP3，可以提升小程序的网络请求性能。有以下注意事项：
- 除声明了 `enableChunked` 后会走 HTTP1 以外，均会自动开启 HTTP2/HTTP3 等优化能力，`enableQuic`、`enableHttp2` 参数将会强制开启。建议开发者在后台服务也开启对应能力以获得更好的效果。
- 暂仅支持 Android，iOS/PC 端设置该参数后会使用原 request 模块。iOS 会在后续支持该参数。
- 暂不支持 HttpDNS 能力。
- 开启 `enableProfile` 后，返回的 profile 字段部分信息缺失，会被缺省值代替。缺失部分包括 redirectStart、redirectEnd、rtt、estimate_nettype、httpRttEstimate、transportRttEstimate、downstreamThroughputKbpsEstimate、throughputKbps、peerIP、port。

## 示例代码

```js
wx.request({
  url: 'example.php', //仅为示例，并非真实的接口地址
  data: {
    x: '',
    y: ''
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success (res) {
    console.log(res.data)
  }
})
```