密钥放哪、失败怎么分:微信小程序 / H5 调用第三方 API 的出口选择
面向小程序与 H5 调用第三方 API 的场景,结论是:需要密钥、计费归属或调用审计的接口不适合从客户端直连,应经自建服务端或云函数中转;跨端差异收敛到统一请求层;失败按网络层、HTTP 层、业务层分类,只对幂等请求重试。文中涉及的小程序域名白名单与浏览器 CORS 具体规则本次未核验,以各自官方文档为准。
- 需要密钥或计费归属的第三方接口,前端只调自己的服务端,不直连。
- 小程序与 H5 的差异集中在请求层,封装成同一入口后换端只改一处。
- 重试只给幂等请求;4xx 不重试,429 先看 Retry-After。
小程序和 H5 都能发 HTTP 请求,但两者对“请求从谁的出口发出”的约束不一样。核心结论只有一句:只要第三方接口需要密钥、按调用计费或需要区分用户身份,就不要从客户端直连;把出口放在你能控制的服务端(自有服务器、云函数或云托管均可),前端只调用自己的接口。理由在于密钥在客户端藏不住、调用无法审计,与性能无关。
边界说明:本文未联网检索,也未引用任何官方文档正文。下文涉及的平台机制按通行设计描述,具体条目、入口与版本差异待核实,请以对应官方文档为准。
先判断:这个接口能不能直连#
- 可以考虑直连:公开、无密钥、不按调用方计费、所有人拿到的内容一致,例如公开的静态资源或公开数据。
- 不建议直连:地址里带
key/token、按调用量计费、需要绑定用户身份、需要留存调用记录。
两端的约束来源不同:小程序端发起网络请求受平台域名配置约束,未在平台侧配置的域名通常会被拒绝;H5 端受浏览器同源策略约束,跨域读取响应需要目标服务返回相应 CORS 响应头。这两条的具体规则与配置入口待核实,但方向是确定的——客户端不是自由的请求出口。
三种出口拓扑#
| 拓扑 | 密钥位置 | 可审计性 | 适用 |
|---|---|---|---|
| 客户端直连第三方 | 客户端(等同于公开) | 无,只能看前端日志 | 公开、无密钥、不计费 |
| 自建服务端 / 云函数中转 | 服务端环境变量 | 可在服务端记录调用方、耗时、状态 | 绝大多数业务接口 |
| 中转 + 缓存与限流 | 服务端 | 同上,且能约束总量 | 多端复用同一接口、需控制成本 |
推断:对一个同时有小程序和 H5 的项目,中转层的收益主要来自“一处限流、一处换密钥、一处改协议”,而非单纯的转发。
把跨端差异收敛到一个请求层#
小程序用 wx.request,浏览器用 fetch,两者在参数命名、错误形态、超时控制上都不一致。建议对外只暴露一个 request(path, options),把差异关在实现里。下面这段是 未执行的示例,仅示结构,域名与路径均为占位:
// 未执行示例:占位域名,仅示意 H5 侧封装
const BASE = 'https://api.example.com'; // 占位
export async function request(path, { method = 'GET', body, timeout = 8000 } = {}) {
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), timeout);
try {
const res = await fetch(BASE + path, {
method,
headers: { 'content-type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
signal: ctrl.signal,
});
if (!res.ok) throw Object.assign(new Error('http'), { kind: 'http', status: res.status });
return await res.json();
} catch (e) {
throw Object.assign(e, { kind: e.kind ?? 'network' });
} finally {
clearTimeout(timer);
}
}
小程序侧需要另一份实现,对外签名保持一致。AbortController 在小程序运行环境中是否可用,取决于基础库与运行环境,待核实;不可用时改用框架自带的取消能力,不要省略超时。
失败分支:先分类,再决定是否重试#
- 网络层失败(没连上、超时、被中断):先明确请求是否可能已到达服务端,再决定重试。
- HTTP 4xx:参数或权限问题,重试通常无效;
429例外,但应先读Retry-After。 - HTTP 5xx 与业务错误码:业务错误码要走响应体解析,不能只看状态码。
建议:只对幂等请求自动重试(GET、或带幂等键的写操作),并设总预算(次数上限 + 总耗时上限),避免超时叠加放大流量。前端同时要有提交中状态,防止用户重复点击变成重复写入。
上线前的最小清单#
- 客户端请求的域名是否都已在平台侧配置(小程序)或已确认 CORS 策略(H5);具体入口待核实。
- 构建产物里搜一遍密钥字段,确认第三方 key 只出现在服务端配置中。
- 每个请求都有超时;重试有次数与总时长上限。
- 日志记录调用方、状态码、耗时,但不记录密钥与完整响应体。
- 换端验证:只改请求层实现,业务代码不动。
如果以上前两条无法确认,先不要上线,因为其余优化都建立在这个前提上。