调用方期望的响应 data 类型;只影响 TypeScript,不做运行时 schema 校验。
URL、方法、查询、body、Header、Host timeout 与 SDK 状态校验配置,详见 MiniProgramNetworkRequestConfig。
通过 validateStatus 的标准化 MiniProgramNetworkResponse;默认仅 2xx
resolve。响应包含安全 Header 与公开 config 快照。
HbMiniProgramNetworkError Host 已完成 HTTP 响应,但状态未通过
validateStatus 时抛出;错误的 status、data、安全 headers、config 与 response
可用于业务分支。它不表示权限、bridge 或网络不可达。
HbMiniProgramSDKError 配置/数据/Header 非法时返回 INVALID_PARAMS;当前运行快照
缺少 network 时返回 PERMISSION_NOT_IN_SNAPSHOT;权限未启用或未获官方域名批准时返回
PERMISSION_DENIED;Host 不支持请求形态时返回 REQUEST_UNSUPPORTED,Host/transport
失败返回 REQUEST_FAILED,Host 能力关闭或旧 Runtime 不认识 method 时可返回
METHOD_FORBIDDEN / METHOD_NOT_FOUND,响应结构无效返回 INVALID_NETWORK_RESPONSE;
其他握手、bridge 或 Host 错误保留对应 SDK 错误码。
移动端访问官方域名时,当前 API 不支持同时使用 JSON/自定义请求头和自动附加的 客户端签名,也没有强制启用签名的配置项。依赖客户端签名的接口应使用服务端支持的 GET 或兼容表单 POST,并避免自定义请求头。接口同时要求两者时,应先与服务端约定 兼容的请求格式或鉴权方式。访问权限已获批、Cookie 可用或请求成功均不代表已签名, 具体编码与兼容规则见 MiniProgramNetworkRequestConfig.data。
该 API 需要在 package.json#heybox.permissions 声明并启用 network,且取得平台批准;
不需要 filesystem 或可信用户手势。useOfficialDomain 只有开发者声明与平台批准都为
true 时生效,并且不会绕过 HTTPS、敏感路径、Header、body、timeout 或响应策略。
公开请求使用 no-follow redirect policy。3xx 不会自动访问 Location;它作为已完成响应
返回到 SDK,默认触发 HbMiniProgramNetworkError,只有自定义 validateStatus
接受时才 resolve。平台保留的 Runtime auth/OpenAPI 路径始终不能通过该能力访问。
自正式版 0.8.1 起公开 config 不再支持 withCredentials;JavaScript 仍传入时会被 SDK
忽略且不报错,也不会把凭据开关传给 Host。原生 Cookie 是否随请求发送由 Host 按目标
域名决定,iframe Cookie 不会由 SDK 自动读取;响应中的 Set-Cookie 与认证 Header 不会
暴露给页面。应用显式 Header 仍必须遵守敏感信息边界。
Browser Dev Host 与真实 App Host 都拒绝 multipart,并执行相同的 no-follow、官方域名和 敏感路径策略;本地代理另有 5 MiB 响应体上限,真机 Host 仍可能有不同的响应限制。
Host 的 config.timeout 与 SDK 等待 bridge 响应的超时彼此独立;默认 SDK 实例从请求
发出后最多等待 10 秒。因此即使传 timeout: 30000,也可能先以 REQUEST_TIMEOUT 拒绝。
SDK 等待超时不会主动取消 Host 请求,也不能证明服务端未处理请求;写请求重试应使用
幂等键或先核实业务结果,避免重复执行。
import hbSDK from '@heybox/hb-sdk'
type ItemsResult = { items: string[] } | { message: string }
const response = await hbSDK.network.request<ItemsResult>({
url: 'https://api.example.com/items',
method: 'POST',
params: { page: 1, locale: 'zh-CN' },
data: { filters: ['owned'] },
headers: { 'content-type': 'application/json', 'x-request-id': 'request-1' },
timeout: 10_000,
validateStatus: (status) => (status >= 200 && status < 300) || status === 404,
})
if (response.status === 404) console.log('暂无数据')
else if ('items' in response.data) console.log(response.data.items)
发起网络请求。
注意:在移动端访问官方域名时,JSON 请求体或自定义请求头不会自动附加客户端签名。