> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# request

发起网络请求。

`request` 本身不接受泛型参数；如需业务数据类型，请读取 `result.data` 后再做类型收窄或断言。

## 扫码预览

![扫码预览 request](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Frequest%252Findex)

## 使用限制

> \[!WARNING]
> **Android、iOS**：Android 仅支持 GET/POST/PUT/DELETE，其余方法返回 "Illegal method"；iOS 仅支持 GET/POST，其余方法返回 "method type not supported"；调用 PUT/DELETE 时 iOS 会失败；调用 HEAD/OPTIONS/TRACE/CONNECT 时双端均失败。
> **Android、iOS**：Android 将二进制响应以 base64 字符串返回；iOS doubao.request 路径不启用 arraybuffer 支持，返回 base64 编码字符串；调用方按 ArrayBuffer 解析会失败。

## 支持版本

前端库版本不低于 `0.0.17`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 使用说明

返回 statusCode、header 和 data。

## 调用方式

### 异步 API

```typescript
request(params: RequestParams): Promise<RequestResponse>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>data</code></td><td><code>string | ArrayBuffer | Record&lt;string, any&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>请求体数据。<br><br>传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：<br>- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；<br>- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；<br>- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；<br>- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；<br>- 其他类型会调用 `toString()`</td></tr>
<tr><td><code>dataType</code></td><td><code>&quot;string&quot; | &quot;json&quot; | &quot;arraybuffer&quot;</code></td><td>否</td><td><code>&quot;json&quot;</code></td><td>-</td><td>期望返回的数据格式。<br>- `json`：尝试按 JSON 解析；<br>- `string`：按字符串返回。<br>- `arraybuffer`：按二进制数据返回。</td></tr>
<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>{&quot;content-type&quot;: &quot;application/json&quot;}</code></td><td>-</td><td>请求 Header。</td></tr>
<tr><td><code>method</code></td><td><code>RequestMethod</code></td><td>否</td><td><code>&quot;GET&quot;</code></td><td>-</td><td>请求方法。Android、iOS：Android 仅支持 GET/POST/PUT/DELETE，其余方法返回 &quot;Illegal method&quot;；iOS 仅支持 GET/POST，其余方法返回 &quot;method type not supported&quot;。</td></tr>
<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>请求地址，需为完整的 HTTP 或 HTTPS URL。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { request } from '@doubao-dev/framework/api';

const result = await request({
  url: 'https://postman-echo.com/post',
  method: 'POST',
  dataType: 'json',
  header: { 'content-type': 'application/json' },
  data: { hello: 'world' }
});

console.log(result.statusCode, result.data);
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>data</code></td><td><code>string | ArrayBuffer | Record&lt;string, any&gt;</code></td><td>否</td><td>响应数据，类型由 `dataType` 决定。</td></tr>
<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>是</td><td>HTTP 响应头。</td></tr>
<tr><td><code>statusCode</code></td><td><code>number</code></td><td>是</td><td>HTTP 状态码。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "statusCode": 200,
  "header": {
    "content-type": "application/json"
  },
  "data": {
    "hello": "world"
  }
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 305,
  "errMsg": "network failure"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>url 为空、method 非法，或请求参数、请求体校验失败</td><td>修正 url、method 与请求参数后重试。</td></tr>
<tr><td><code>110</code></td><td><code>API call prohibited</code></td><td>Android、iOS</td><td>请求 URL 未通过域名白名单校验</td><td>确认目标域名已在应用插件中配置后重试。</td></tr>
<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>网络请求被取消</td><td>确认应用与网络状态后重试。</td></tr>
<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>Android、iOS</td><td>网络连接超时</td><td>检查网络连接后重试。</td></tr>
<tr><td><code>303</code></td><td><code>no network connection</code></td><td>Android、iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：网络失败仅细分为 302（HTTP 408 超时）、303（无网络连接）与 305（其他网络错误），不返回 301；url 为空或 method 非法返回 104；命中域名管控返回 110。
- **iOS**：依据 NSURLError 细分网络失败：请求取消 301、连接超时 302、无网络 303、其他 305；参数或请求体校验失败返回 104；命中域名管控返回 110；其他失败统一返回 102。
