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, and this page is available as Markdown at /apps-plugin/docs/js-api/network/request.md.

request

发起网络请求。

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

扫码预览

扫码预览 request

使用限制

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。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

使用说明

返回 statusCode、header 和 data。

调用方式

异步 API

request(params: RequestParams): Promise<RequestResponse>

入参

名称类型必填默认值约束说明
datastring | ArrayBuffer | Record<string, any>否--请求体数据。

传给服务器的数据最终会是 String 或 ArrayBuffer:
  • 若 data 是 string 或 ArrayBuffer,直接使用;
  • 若 header['content-type'] 是 application/x-www-form-urlencoded,会被编码为 query string,例如:encodeURIComponent(k)=encodeURIComponent(v);
  • 若 header['content-type'] 是 application/json,会执行 JSON 序列化;
  • 若 data 是普通对象且未命中上述类型,也会执行 JSON 序列化;
  • 其他类型会调用 toString()
dataType"string" | "json" | "arraybuffer"否"json"-期望返回的数据格式。
  • json:尝试按 JSON 解析;
  • string:按字符串返回。
  • arraybuffer:按二进制数据返回。
headerRecord<string, string>否{"content-type": "application/json"}-请求 Header。
methodRequestMethod否"GET"-请求方法。Android、iOS:Android 仅支持 GET/POST/PUT/DELETE,其余方法返回 "Illegal method";iOS 仅支持 GET/POST,其余方法返回 "method type not supported"。
urlstring是--请求地址,需为完整的 HTTP 或 HTTPS URL。

调用示例

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);

成功返回

名称类型必返说明
datastring | ArrayBuffer | Record<string, any>否响应数据,类型由 `dataType` 决定。
headerRecord<string, string>是HTTP 响应头。
statusCodenumber是HTTP 状态码。

返回示例

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

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

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

错误码

errNoerrMsg平台触发条件处理建议
104invalid parameterAndroid、iOSurl 为空、method 非法,或请求参数、请求体校验失败修正 url、method 与请求参数后重试。
110API call prohibitedAndroid、iOS请求 URL 未通过域名白名单校验确认目标域名已在应用插件中配置后重试。
301network request cancellediOS网络请求被取消确认应用与网络状态后重试。
302connection timed outAndroid、iOS网络连接超时检查网络连接后重试。
303no network connectionAndroid、iOS当前无可用网络连接恢复网络连接后重试。
305network failureAndroid、iOS发生其他网络错误检查网络连接,稍后重试。

通用错误码

errNoerrMsg说明平台
102internal error内部错误iOS

平台差异

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