小程序与 H5 调用第三方 API:先决定谁发起,再谈怎么发
客户端直连第三方 API 的可行性取决于两端各自的约束:小程序受后台配置的 request 合法域名限制,H5 受浏览器同源策略与对方 CORS 响应头限制。更稳的做法是把第三方调用收敛到服务端出口,客户端只下发业务参数;密钥、超时、重试与错误归一都在服务端完成。调用失败应分层处理,HTTP 200 不等于业务成功。文中平台规则的具体判定与数值需以官方文档核对,本次未联网验证。
- 直连方案要同时在小程序域名配置和对方 CORS 两头成立,缺一不可。
- 密钥不放在小程序包或前端代码里,两者都能被读出。
- 把网络失败、HTTP 状态、业务码、响应结构分开处理,避免把 200 当成功。
结论先行:讨论“调用姿势”之前,先回答一个问题——这次请求该由谁发起。微信小程序和 H5 都能发出 HTTPS 请求,但两者能不能直达第三方 API,取决于各自的平台约束;只要涉及密钥、需要重试与对账、或对方不支持跨域,就应该走服务端出口,客户端只负责提交业务参数。
先判断这次调用该由谁发起#
可以用三个问题做初筛,任何一个答案为“是”,服务端出口都更合适:
- 请求需要携带密钥吗?小程序包可被解包分析,H5 的前端代码对用户可见,长期密钥放在客户端等于公开。
- 对方接口支持浏览器跨域吗?如果不返回相应的 CORS 响应头,H5 直连会在预检阶段失败;小程序不走浏览器同源策略,但另有域名配置这道门。
- 需要统一重试、限流、日志或计费口径吗?这些逻辑放在客户端无法收敛,也无法防止被绕过。
三问都不触发时,客户端直连可以接受,例如调用公开的、无需凭证的查询接口。
两端各自的硬约束#
小程序侧:网络请求使用 wx.request,请求域名需在小程序管理后台配置为合法域名,通常要求 HTTPS。开发者工具里的调试开关不等于线上可用——真机与线上环境仍按后台配置校验。域名数量上限、审核要求与具体校验规则以微信官方文档为准,本文未联网核验。
H5 侧:受浏览器同源策略约束,跨域请求是否放行由对方服务端的 CORS 响应头决定,预检请求(OPTIONS)也可能被拦截。这一机制属于浏览器与 Fetch 标准的通用行为,具体细节可对照 MDN 或标准文本核对。
两者不能互相替代:小程序能直连,不代表同一套前端代码放到 H5 也能跑通。
客户端只做三件事#
把第三方调用收进服务端后,客户端代码会明显变薄:拼参数、设超时、分错误。下面两段均为未执行的示例,只示意结构,不代表任何真实端点或返回。
// 未执行示例:小程序端,占位域名,不带任何密钥
const API_BASE = 'https://api.example.com';
function callApi(path, data) {
return new Promise((resolve, reject) => {
wx.request({
url: API_BASE + path,
method: 'POST',
data,
timeout: 8000, // 具体取值按业务与平台限制自定
header: { 'content-type': 'application/json' },
success(res) {
if (res.statusCode >= 200 && res.statusCode < 300) resolve(res.data);
else reject({ kind: 'http', status: res.statusCode });
},
fail(err) { reject({ kind: 'network', err }); }
});
});
}
// 未执行示例:服务端出口,密钥只从环境变量读取
app.post('/api/proxy', async (req, res) => {
try {
const upstream = await fetch('https://third-party.example.com/v1/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + process.env.UPSTREAM_KEY, // 占位:YOUR_KEY
'content-type': 'application/json'
},
body: JSON.stringify(req.body),
signal: AbortSignal.timeout(8000) // 需运行时支持,未核实你的环境
});
const body = await upstream.json();
// 按契约判断业务码,而不是只看 HTTP 200
res.status(upstream.ok && body.code === 0 ? 200 : 502).json(body);
} catch (e) {
res.status(504).json({ error: 'upstream_unavailable' });
}
});
失败要分层,别把 200 当成功#
下表是按处理方式划分的建议,不是平台规定:
| 层次 | 典型表现 | 建议处理 |
|---|---|---|
| 传输层 | DNS、TLS、连接超时 | 仅对幂等请求有限重试,其余提示网络异常 |
| HTTP 状态 | 401 / 403 / 429 / 5xx | 凭证与权限类不重试;限流类读取对方给出的重试提示 |
| 业务码 | HTTP 200 但响应体内 code 非成功值 | 按对方契约映射,不计为成功 |
| 响应结构 | 字段缺失、类型变化 | 校验后再进入业务逻辑,异常时记录原始响应 |
上线前值得核对的项目#
- 请求域名是否已在后台配置,线上真机走一遍,而不只在开发者工具里自测。
- 客户端代码与打包产物中是否残留任何密钥。
- 超时值是否小于调用链上一层的超时,避免雪崩。
- 错误分类是否覆盖上面四层,日志里能否区分“没发出去”“发出去了失败”“成功了但业务失败”。
- 对方接口的限流口径、配额与计费方式,以对方文档为准——本次材料未提供,待核实。
把这几项定清楚,两端的差异就退化成配置问题,而不是上线后才暴露的故障。