微信小程序 / H5 调用第三方 API 的正确姿势:密钥放哪、请求怎么封、失败怎么算
前端(小程序或 H5)不适合持有第三方 API 密钥,通常应由自有服务端转发并统一做鉴权、配额与错误映射;只有第三方接口本身公开、无凭证且允许跨域时,前端直连才成立。请求封装要覆盖超时、状态码判读、错误分类与幂等重试;小程序的合法域名配置与浏览器 CORS 是两条不同的约束,具体规则本次未核验。
先给结论:把第三方 API 的密钥留在你自己的服务端,前端(微信小程序或 H5)只请求自有域名。前端直连第三方只在一种情况下成立——该接口本身是公开的、不需要凭证、且允许被浏览器跨域调用。其余情况,前端直连等于把凭证发给每一个打开页面的用户。
本文没有可核验的接口文档与测试记录,因此不提供任何具体接口的限额、超时数值或性能结论;带数字的地方都需要你按自己的接口文档核对。
一、先判断:这次调用属于哪一类#
- 需要密钥或账号配额:走自有服务端代理。前端不接触 key,服务端负责注入凭证、限流、缓存和计费统计。
- 完全公开、无凭证:可以考虑前端直连,省一跳。但要先确认第三方是否返回允许跨域的响应头(H5),以及域名能否加入小程序白名单。
- 返回数据含隐私或需要审计:即使接口公开,也建议经服务端转发,否则调用链路上没有你可控的日志点。
二、小程序侧:约束在“域名白名单”,不在代码#
小程序的网络请求走宿主提供的 wx.request,可请求的域名需要在平台侧提前配置,不能靠运行时代码临时决定。开发工具与真机的校验行为可能不同,具体规则和数量限制请以官方文档为准(本次未核验,不列数字)。
这意味着:把第三方域名直接写进小程序,等于把对方的域名、可用性和变更节奏绑进你的发布流程。经自有服务端转发后,小程序只需要配置一个自己的域名。
请求封装的最小骨架
下面代码未执行,仅示结构;域名与路径为占位,需替换为你自己的服务端地址。
// 未执行示例:仅示结构
const API_BASE = 'https://api.example.com'; // 占位域名,指向自有服务端
function request(path, { method = 'GET', data, timeout = 8000 } = {}) {
return new Promise((resolve, reject) => {
wx.request({
url: API_BASE + path,
method,
data,
timeout,
header: { 'content-type': 'application/json' },
success(res) {
if (res.statusCode >= 200 && res.statusCode < 300) {
return resolve(res.data);
}
reject(Object.assign(new Error('HTTP_ERROR'), {
statusCode: res.statusCode,
body: res.data
}));
},
fail(err) {
reject(Object.assign(new Error('NETWORK_ERROR'), { cause: err }));
}
});
});
}
注意这段封装里没有任何密钥。这是刻意的:前端代码可被反编译、可被浏览器查看,写在里面的凭证都应视为已泄露。
三、H5 侧:先分清跨域失败和接口失败#
浏览器受同源策略约束。第三方接口如果没有返回允许你所在源访问的响应头,请求会在浏览器端被拦截,此时你往往拿不到对方的状态码,也读不到响应体。这类失败的排查方向是“跨域配置”,不是“参数写错了”。
常见处理顺序:
- 确认第三方是否官方支持浏览器直连;不支持就走自有服务端代理。
- 代理层负责注入密钥、设置超时、把上游响应整理成你自己的稳定结构。
- 前端只认自己的错误码,不直接依赖第三方错误文案。
四、失败怎么算:三类错误不要混在一起#
| 类别 | 典型来源 | 可做的处理 |
|---|---|---|
| 网络/超时 | 链路中断、上游过慢 | 仅对幂等请求重试;带退避,限制次数 |
| HTTP 状态错误 | 4xx / 5xx | 4xx 一般不重试,5xx 可有限重试 |
| 业务错误 | 200 但体内标记失败 | 按对方文档判读字段,不能只看状态码 |
重试的前提是幂等:查询类接口重试通常安全;下单、扣费、发消息类接口重复执行会产生副作用,需要业务侧的去重键或请求 ID。具体哪些接口幂等,取决于第三方文档,本次无法核验。
五、上线前值得逐条核对的项#
- 前端产物里搜不到第三方 key、token 或账号标识。
- 小程序后台配置的请求域名与代码中实际使用的域名一致。
- 超时时间有明确取值理由,而不是默认值随手留着。
- 第三方错误被映射成自有错误码,原始报错不直接透给用户。
- 配额与限流在服务端有计数点,能回答“今天调了多少次”。
- 上游不可用时的降级行为已写清:返回缓存、返回空态,还是明确报错。
这些项不依赖某一家服务商的细节,属于接入前就能自证的工程约束。至于具体接口的字段语义、限流阈值与是否支持浏览器直连,需要以对应官方文档为准——本文未做核验,也不替代那一步。