微信小程序 / H5 调用第三方 API:密钥、代理层与适配层怎么分工
小程序和 H5 都不应持有第三方 API 密钥,应把调用收敛到自家服务端代理层;两端在请求方式、超时、跨域与域名白名单上的差异,统一放到一层薄适配层处理,再向业务代码暴露归一化的响应与错误语义。文中给出了未执行的示例骨架,并列出需以官方文档核实的事项。
最简短的答案是:密钥不要出现在小程序包或 H5 页面里,第三方调用走自家服务端代理;小程序与 H5 的请求差异留在薄薄一层适配层,不要把差异渗进业务代码。下面分别说明这么做的原因、分层边界,以及哪些细节需要你回官方文档核实。
为什么不能在前端直连第三方#
小程序代码包可以被解包查看,H5 的 JavaScript 会完整下发到浏览器,任何写在客户端的 API Key 都等同于公开。因此即使第三方接口本身允许浏览器直接请求,只要它需要密钥或计费额度,就应该由服务端持有凭证并代为转发。
此外,两端都存在请求限制:H5 受同源策略约束,跨域请求需要对方返回正确的 CORS 响应头;小程序端的网络请求通常受请求域名白名单约束,具体配置入口、审核口径与限制条件以微信官方文档为准(本文未核实具体版本与细则,待核实)。
三层分工:代理层、适配层、业务层#
- 服务端代理层:唯一持有密钥的地方。负责鉴权、参数校验、超时控制、限流与日志脱敏,把第三方的响应裁剪成自家契约。
- 适配层:运行在客户端,只处理平台差异——请求 API、超时、存储、错误对象形态。它不关心业务字段含义。
- 业务层:只消费归一化后的结果,不出现
wx.或fetch之类环境相关调用。
需要提前确认的一点:第三方服务的条款是否允许你这样代理转发、是否对出口 IP 或调用频次有额外要求——这属于待核实项,不能默认为允许。
适配层示例(未执行)
以下代码仅示意结构,未实际执行,域名与凭证均为占位:
// 未执行的示例|占位域名 example.com,凭证来自服务端环境变量
const transport = {
// 小程序环境:始终请求自家后端,不直连第三方
weapp: (path, body) => new Promise((resolve, reject) => {
wx.request({
url: `/api/proxy${path}`,
method: 'POST',
data: body,
timeout: 8000,
success: (r) => (r.statusCode === 200 ? resolve(r.data) : reject(r.data)),
fail: reject,
});
}),
// H5 环境:同源请求,避免额外跨域配置
h5: async (path, body) => {
const r = await fetch(`/api/proxy${path}`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
signal: AbortSignal.timeout(8000),
});
if (r.ok) return r.json();
throw await r.json().catch(() => ({}));
},
};
注意 H5 侧写成相对路径 /api/proxy,是为了让请求与页面同源,把跨域问题留给服务端之间的调用,而不是留给浏览器。
把响应和错误先归一化#
第三方返回的字段名、错误码体系各不相同,若直接透传给业务层,换个供应商就要改遍调用点。建议代理层输出固定信封,例如 { ok, code, message, data },并约定三类可区分的情况:
- 调用方错误(参数不合法):不要重试。
- 上游错误(第三方超时、限流、5xx):可有限次退避重试,但对非幂等接口需先确认语义。
- 鉴权/额度错误:应告警而非重试,否则会放大计费或触发风控。
哪些状态码算可重试、重试几次、超时设多少,取决于具体第三方的文档与你的 SLA 要求,本文不给出统一数值。
落地前建议确认的边界#
- 第三方的服务条款、配额与价格:待核实,不同版本差异可能很大。
- 小程序请求域名白名单的具体要求与审核规则:以官方文档为准。
- 代理层日志是否记录了不该记录的字段(凭证、用户标识):建议默认脱敏。
- 密钥轮换路径:密钥只在服务端,轮换才不会牵动客户端发版。
一句话收束:密钥归服务端,平台差异归适配层,语义归一化归代理层,业务代码只认自家契约。