@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...

    接口 MiniProgramNetworkRequestConfig

    对外开放的网络请求配置。

    该配置面向业务层,保持 axios-like 的窄接口,不暴露宿主协议的原始字段。请求进入 bridge 时会复制 plain object/array 数据并移除 validateStatus;响应中的 config 由 SDK 另行构造。

    interface MiniProgramNetworkRequestConfig {
        data?: unknown;
        headers?: MiniProgramNetworkHeaders;
        method?: MiniProgramNetworkRequestMethod;
        params?: MiniProgramNetworkParams;
        timeout?: number;
        url: string;
        validateStatus?: MiniProgramNetworkValidateStatus;
    }
    索引

    属性

    data?: unknown

    请求体。

    支持可序列化的 JSON-compatible 值与原始字符串,总大小不得超过 2 MiB。plain object/array 会递归复制,因此复用同一子对象可以,但循环引用会以 INVALID_PARAMS 拒绝。GET/HEAD 不应携带 body。

    第三方 URL 的非字符串 JSON-compatible 值默认按 JSON 发送;官方域名为兼容既有 Host, plain object/array 在未显式设置 Content-Type 时默认按 form 编码。要强制 JSON,请设置 Content-Type: application/json;表单请传 new URLSearchParams(values).toString() 并设置 application/x-www-form-urlencoded。

    在移动端访问官方域名时,JSON 请求体或自定义请求头不会自动附加客户端签名。 依赖客户端签名的接口应使用服务端支持的 GET 或兼容表单 POST,并避免自定义请求头; 标量表单对象及无重复字段的合法 UTF-8 表单字符串可兼容。仅设置表单 Content-Type 用于声明编码,不影响这类表单请求的兼容性。

    当前 API 不支持在同一请求中同时使用 JSON/自定义请求头和自动附加的客户端签名, 也没有强制启用签名的配置项。接口同时要求两者时,应先与服务端约定兼容的请求格式 或鉴权方式,并在目标客户端验收。官方域名访问权限、Cookie 可用、SDK 版本或请求 成功均不能作为已签名的依据。历史客户端仍可能以 REQUEST_UNSUPPORTED 拒绝。 GET/HEAD 不携带正文。此限制不影响第三方 URL 的自定义请求头与 JSON 请求能力。

    不支持 FormData、Blob、File/Directory 代理、ArrayBuffer、TypedArray、DataView、 SharedArrayBuffer 或它们的嵌套值。multipart/form-data 与手写 multipart body 均不可用; 文件传输应使用专用能力。

    请求头;规则见 MiniProgramNetworkHeaders。调用方显式提供的普通 Cookie / Authorization 可作为应用 Header 交给 Host,但 SDK 不提供平台 Cookie/token,且不得在 小程序中持有或发送平台凭据、服务端应用密钥等敏感信息。 在移动端访问官方域名时,自定义请求头不能与自动附加的客户端签名同时使用。 依赖客户端签名的接口应避免自定义请求头。仅声明表单 Content-Type 的兼容规则 见 MiniProgramNetworkRequestConfig.data。

    HTTP 方法,默认 GET;仅支持 MiniProgramNetworkRequestMethod 中列出的值。

    查询参数;必须是普通对象,SDK 会递归复制 plain object/array 后交给 Host 编码。

    timeout?: number

    Host 请求超时,单位毫秒;必须是 0 至 30000 的有限数字。省略或 0 时的具体默认 行为由 Host 决定;业务需要明确超时时应传正数。该字段不改变 SDK 等待 bridge 响应的 独立超时;默认 SDK 实例的等待上限为 10 秒,详见 MiniProgramNetworkModule.request。

    url: string

    绝对请求地址。必须是无 username/password 的 HTTP(S) URL;生产环境只允许 HTTPS,本地 开发仅允许 Host 明确放行的数字 loopback/LAN HTTP origin。官方域名要求 package.json#heybox.permissions.network.useOfficialDomain 的声明值与平台批准值都为 true;Runtime auth、OpenAPI 内部路径和官方账号敏感路径始终禁止访问。

    SDK 侧状态校验;默认只接受 2xx,函数本身不会跨 bridge,详见 MiniProgramNetworkValidateStatus。