第三方 API 不该由客户端直连:小程序与 H5 的统一出口设计
一句话回答
小程序与 H5 调用第三方 API 的正确做法,是把调用链拆成客户端、自家服务端出口、上游三段:密钥与签名只留在服务端,平台差异只影响客户端这一小段,服务端对外提供统一的外层结构与错误码映射。本次没有可核验的素材,平台级配置细节与端点行为均需以官方文档为准。
先说结论:这件事的正确做法,是在客户端和第三方 API 之间加一层自家服务端出口,端上只跟自家后端说话;它并不是写一个“能发请求的函数”。在小程序和 H5 里,真正需要区别对待的只有最靠近用户的那一小段,密钥、签名、重试和错误码映射都应该落在服务端。本文讨论的是结构边界,具体的平台配置项与上游接口行为,本次材料没有覆盖,需以官方文档核实。
为什么先设统一出口#
判断依据是部署常识:H5 的脚本对用户可见,小程序包也可被解包查看,任何写进客户端的密钥都应视为已经泄露。一旦泄露,轮换成本、配额被消耗的损失都由你自己承担,且难以定位来源。
统一出口还带来一个维护上的好处:域名、超时、重试策略、错误码映射只在服务端一处维护。如果让每个页面各自直连上游,上游改一次字段,就要改很多地方。
平台差异只影响客户端层#
- H5:请求由浏览器发出,跨域能否放行取决于目标服务端返回的 CORS 响应头。第三方 API 一般不会为你的页面域名放行,这一点在动手写代码前就应确认。
- 小程序:请求能力、可请求域名的配置方式、是否支持自定义请求头、上传下载接口的差异,都由平台规则约束。本次材料未提供文档,这些细节待核实,不要凭记忆写死。
由此得到一个可操作的推论:不要为了兼容第三方而在客户端堆一层“平台适配”。把差异收在服务端出口的一侧,客户端只保留一种调用方式。
服务端出口的最小契约#
- 输入:只接收业务参数,不接收密钥,也不接收上游地址。
- 输出:统一外层,例如
{ code, message, data };上游错误码映射成自家码,不要把上游原始错误体透传给客户端,它可能包含内部信息。 - 超时与重试:为上游设置明确超时;仅在幂等请求上重试,非幂等写操作要带幂等键。
- 日志:记录 requestId、耗时、上游状态码;不记录密钥与完整个人数据。
客户端只做三件事#
- 携带自家会话凭证,而不是上游密钥;
- 校验外层结构,缺失字段按失败处理;
- 区分可重试与不可重试:网络类失败可提示重试,参数类失败重试没有意义。
一个结构示例(未执行)#
下面的代码未实际运行,仅示意服务端出口的形状,地址与密钥均为占位。运行环境假设为 Node.js 18+ 并使用原生 fetch,该假设本身需自行核实。
// 未执行示例:占位地址与占位密钥,不含真实端点
export async function callUpstream(params) {
const url = "https://api.example.com/v1/items"; // 占位
const res = await fetch(url, {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.UPSTREAM_KEY}` // YOUR_KEY 由环境变量注入
},
body: JSON.stringify(params),
signal: AbortSignal.timeout(5000)
});
if (!res.ok) {
// 这里应映射为自家错误码,而不是透传上游文案
return { code: "UPSTREAM_ERROR", message: "上游调用失败", data: null };
}
return { code: "OK", message: "", data: await res.json() };
}
什么情况下可以考虑不经过服务端#
范围很窄:公开只读、不要求密钥、没有按账号配额的接口。即便如此,也要考虑速率限制与缓存,并且要确认平台是否允许该类域名——这一条待核实。
判断标准很简单:如果这个调用失败或密钥泄露会直接影响账号或费用,它就不该从端上发出。
上线前的检查项#
- 在客户端产物里搜索密钥字段,确认搜不到;
- 错误码映射表存在,且客户端对未知码有兜底;
- 上游接口变更或不可用时,有可回滚的开关;
- 平台侧域名、权限配置与官方文档核对过,而不是照抄旧文。
以上是结构层面的建议,不构成对任何具体平台配置或上游接口行为的结论;涉及版本、配额、可用性的信息,本次材料均未提供。