微信小程序与 H5 调用第三方 API：先定信任边界，再谈直连

先说结论：不要让长期密钥进入小程序包或 H5 代码；只有低风险的公开只读接口才适合考虑直连，其余请求更稳妥的做法是经过自有服务端中转。所谓“正确姿势”，主要是先定信任边界，再谈请求怎么写。

先判断能不能从客户端直连#

建议按风险分三档：

• 无密钥的公开只读接口：在配额、缓存以及跨域或域名配置允许时，可考虑直连；但仍要避免把“配额耗尽”误判成“接口坏了”。
• 需要密钥、写操作或计费的接口：不建议把长期密钥放进客户端。客户端可拿短期业务令牌，由自有服务端注入第三方密钥。
• 涉及支付、隐私、权限的接口：需要服务端校验与审计，前端只负责发起和展示。

这样做并不是因为直连一定错，而是因为只要密钥进入用户可控环境，就应按“已经泄露”来设计。

小程序与 H5 的约束不同#

H5 按浏览器规则处理：跨域请求是否放行，取决于第三方是否返回合适的 CORS 响应头；带 Cookie 的请求还涉及凭证模式。前端单方面改代码不能绕过同源策略。

小程序侧通常涉及请求域名配置、HTTPS 与证书链等要求，具体规则以平台当前文档为准，本文未联网核验。如果出现开发者工具能通、真机不通，优先排查域名与证书，不要先怀疑业务代码。

推荐的最小结构：客户端 → 自有网关 → 第三方#

网关不必做得很重，但建议承担四件事：

1. 注入密钥与租户标识，避免密钥下发到客户端；
2. 设置连接超时、读取超时与重试预算，防止请求堆积；
3. 把第三方错误码归一为自有错误模型；
4. 记录脱敏日志与调用量，便于对账和限流。

客户端只处理交互与可恢复提示。例如超时后展示“稍后重试”，不要无限转圈。

契约要覆盖失败，而不只是覆盖成功#

接入前建议写清楚：超时多少、哪些请求可重试、最多重试几次、是否幂等、缓存多久、限流返回什么。一般原则是：只对幂等请求自动重试；429 优先尊重 Retry-After；非幂等写操作若要重试，需要幂等键。

缓存也不要顺手就加：只有响应语义允许缓存，而且缓存键能区分用户、租户和关键参数时才缓存，否则容易把 A 用户的数据返回给 B 用户。

上线前核对#

• 第三方是否允许浏览器直连，CORS 与凭证模式是否匹配；
• 小程序请求域名、HTTPS 证书链是否满足平台要求（待按文档核实）；
• 配额、计费单位与超限行为是否清楚；
• 失败降级、重试上限与告警是否就位；
• 日志是否脱敏，是否记录必要的请求 ID 以便追查。

结论#

“正确姿势”不是找到一段能跑的请求代码，而是把信任边界放在服务端、把平台约束当前提、把失败契约写进接口设计。无法确认第三方当前是否支持客户端直连时，先按“自有网关中转”实现，通常比事后把密钥从前端撤下来成本更低。