小程序与 H5 调用第三方 API 的正确姿势:把差异关进封装层,把错误当成契约
一句话回答
小程序与 H5 调用第三方 API 的三个关键点:长期密钥只留在服务端,客户端使用短期凭证;两端差异收敛到一层 transport 封装;域名白名单、超时与错误分类需在上线前按契约验证。平台具体配置项与限制本次无可核验材料,需查官方文档。
可以浓缩成三句话:长期密钥留在服务端,客户端只拿短期凭证;小程序与 H5 的差异收敛在一层请求封装里,而不是散进业务代码;域名白名单、超时和错误分类在开发阶段就按契约验证,而不是上线后再补。以下是建议做法。涉及微信平台具体配置路径、数量上限与请求行为的细节,本次没有可核验的官方正文,均标注为待核实。
一、先判断这个 API 该由谁调用#
第三方 API 大致分两类,处理方式不同:
- 服务端调用:提供方给的是长期 API Key 或 Secret,请求应由小程序或 H5 所在的后端发出,客户端只调自己的业务接口。
- 客户端直连:只在提供方明确支持公开客户端(如带来源限制的公开接口、OAuth 授权码流程)时才适用,且不能携带长期密钥。
小程序包和 H5 的 JavaScript 都会下发到用户设备,把 Secret 写进前端等于公开。这是通用判断,不是针对某个平台的漏洞结论。
二、两端的差异在哪#
| 能力 | 微信小程序 | H5 |
|---|---|---|
| 请求域名 | 需在平台侧配置合法域名,具体入口与数量上限待核实 | 无平台级白名单,受浏览器同源策略与 CORS 约束 |
| 跨域 | 不涉及浏览器 CORS | 第三方域名需返回正确的 CORS 响应头 |
| 会话传递 | 网络请求不依赖浏览器 Cookie 机制,通常靠请求头传递(概括,具体以官方文档为准) | 浏览器按同源与 SameSite 规则自动携带 Cookie |
| 运行环境 | 受平台基础库版本影响,待核实 | 受浏览器版本影响 |
三、把差异关进一个适配层#
定义一个 transport 接口,业务代码只依赖它,平台差异在各自的实现里处理。
// 未执行示例:仅示意结构,不针对任何真实端点
export function createClient({ transport, baseURL, getToken }) {
async function request(path, { method = 'GET', body, timeout = 8000 } = {}) {
const token = await getToken(); // 短期凭证,由自己的后端签发
const res = await transport({
url: baseURL + path,
method,
headers: {
'content-type': 'application/json',
...(token ? { authorization: 'Bearer ' + token } : {}),
},
body: body === undefined ? undefined : JSON.stringify(body),
timeout,
});
if (!res.ok) throw new ApiError(res.status, await res.text());
return res.json();
}
return { request };
}
两个 transport 实现的关键差别:小程序侧由 wx.request 发起并依赖已配置的合法域名;浏览器侧由 fetch 发起,跨域是否成立取决于对方响应头。封装层要统一返回结构,让上层不必写两套解析。
四、错误和超时也是契约#
- 至少区分四类:网络或超时失败、HTTP 状态码、业务错误码、响应解析失败。四类的提示文案与重试策略不应混用。
- 只对幂等请求做有限重试,并设总时长上限;写操作靠幂等键,而不是靠重试碰运气。
- 业务侧超时应小于平台或网关的限制,具体数值待核实。
五、上线前的验证清单#
- 用一条最小可复现请求打通链路,记录请求头、状态码与响应体结构。
- 确认生产域名已进白名单,且与测试环境分离。
- 断网、慢网、5xx 三种情况各验证一次提示与重试行为。
- 在构建产物中搜索密钥关键词,确认 Secret 未被打包。
- 验证凭证过期后的刷新路径,以及刷新失败时的降级表现。
平台侧的具体限制建议直接查阅官方文档对应章节,不要用二手总结替代。本文的代码与清单是结构建议,未在真实环境中执行。