微信小程序与 H5 调用第三方 API:先收住平台差异,再谈请求写法
小程序与 H5 调用同一个第三方 API,差异主要不在业务逻辑,而在运行环境、域名与跨域约束、错误分类方式。可行做法是把平台差异压到一个可替换的接入层:页面只消费统一结果;传输层按错误类型区分可重试与不可重试;只对幂等请求重试;密钥不进入客户端。平台具体的域名白名单与并发限制以官方文档为准,本文未做核验。
“正确姿势”不是先决定在小程序里写 wx.request、还是在 H5 里写 fetch,而是先把两者的差异收进一层可替换的接入代码。页面组件不该知道密钥从哪来、域名白名单怎么配、超时算多少毫秒;它只应该拿到一个结果:成功的数据,或一个能被分类处理的失败。
这个结论有前提:第三方 API 的端点、鉴权方式和配额规则需要你自己核实。本文不涉及任何具体厂商的实测调用,平台规则也在变化,凡是涉及“必须配置什么才能发请求”的部分,都应以官方文档为准(待核实)。
两种运行环境,差异在三个地方#
运行环境。小程序没有 DOM,也没有浏览器的 XMLHttpRequest,网络请求走平台提供的 API;H5 跑在浏览器里,可以直接用 fetch。这决定了两端不能共用同一份“发请求”的代码,但可以共用同一份“处理结果”的代码。
域名与跨域约束。H5 读取跨域响应时会被同源策略拦截,通常需要服务端返回 CORS 响应头,配置方式随服务端框架而异。小程序一般要求在小程序后台配置请求域名,且对协议有要求;具体清单和审核规则请核对官方文档(待核实)。这意味着同一份接口地址,可能在浏览器里通、在小程序里被拦,或者反过来。
失败形态。两端都会遇到断网、超时、限流和 5xx,但抛出的错误对象结构不同。如果不在接入层归一,错误处理代码会在每个页面里重复一遍。
接入层:把差异压到一个函数后面#
下面是一个结构示意,不是可运行实现,也没有实际执行:域名、超时、错误码字段均为占位。
// 未执行的示例:仅演示分层,https://api.example.com 为占位域名
const BASE = 'https://api.example.com'; // 占位
function createClient(transport) {
// transport: 平台适配器,签名统一为 ({url, method, body, timeout}) => {status, data}
return async function request({ path, method = 'GET', body, timeout = 8000 }) {
try {
const res = await transport({ url: BASE + path, method, body, timeout });
if (res.status >= 200 && res.status < 300) return { ok: true, data: res.data };
if (res.status === 429 || res.status >= 500) {
return { ok: false, kind: 'retryable', status: res.status };
}
return { ok: false, kind: 'business', status: res.status, code: res.data && res.data.code };
} catch (e) {
return { ok: false, kind: 'network', error: String(e && e.message) };
}
};
}
两端各写一个 transport:小程序侧用平台的请求 API,H5 侧用 fetch。差异被限制在这一个函数里,换平台时上层不用改。
错误分层:哪些该重试,哪些不该#
| 层次 | 典型表现 | 建议动作 |
|---|---|---|
| 传输层 | 超时、断网、5xx | 可重试,限制次数并退避 |
| 限流 | 429 | 可重试,但先看响应头给出的等待时间 |
| 业务层 | 4xx + 错误码 | 一般不重试,转成用户可理解的提示 |
| 契约层 | 字段缺失、类型变化 | 记日志并降级,不要静默当成功 |
第四行最容易被忽略。第三方 API 返回 200 不代表数据可用;接入层应当校验关键字段是否存在,而不是把整个响应对象直接透传给页面。
重试的两个边界#
- 只对幂等请求重试。GET 通常安全;POST 创建类请求重复发送可能产生多条记录。若要对这类请求重试,需要服务端支持幂等键,是否支持需查对应 API 文档(待核实)。
- 重试要有上限和退避。无限重试在限流场景下会把问题放大;固定间隔重试在多端同时失败时容易形成同步冲击。
密钥与配额#
具备写权限或计费属性的密钥不应出现在小程序包体或前端脚本里:这两类产物都能被提取。若确实要直连,应当假设该密钥是公开的,并据此配置来源限制与配额;更稳妥的做法是把密钥放在服务端,客户端只调自己的接口。这一点在密钥轮换、最小权限等实践里已经反复出现过,本文不展开。
调试顺序#
- 先用命令行或服务端脚本单独验证端点本身,确认请求方法与参数正确。
- 再在浏览器或真机上抓取实际发出的报文,对比 URL、请求头和请求体。
- 若浏览器通、小程序不通,优先查小程序后台的域名配置,而不是改业务代码。
- 若反过来,优先查 CORS 与预检请求(
OPTIONS)是否被正确处理。 - 最后才看业务错误码。
把这五步写成检查清单,比在多个页面里逐个加 console.log 更省时间。至于超时默认值、并发上限这些具体参数,各平台与各 API 的约束不同,需要按你的实际环境和官方文档确定(待核实)。