微信小程序与 H5 调用第三方 API:两端差异、服务端出口与错误分类
小程序与 H5 调用第三方 API 的约束不同:小程序受宿主网络能力与域名白名单约束,H5 受浏览器同源策略与 CORS 约束。共同做法是把第三方调用收进自建服务端出口,两端只保留薄适配层,并统一超时、错误分类与响应校验。域名数量、超时上限、并发限制等平台具体数值本次未核验,应以官方文档为准。
小程序和 H5 调用第三方 API,卡点通常不在“怎么发请求”,而在两端所处的网络环境不一样:小程序里的请求由宿主发起,受域名白名单和宿主网络能力约束;H5 里的请求由浏览器发起,受同源策略与 CORS(跨域资源共享)约束。所以正确的姿势不是把一份代码复制两遍,而是让两端都只调用自家服务端的一个薄接口,由服务端去对接第三方 API。
需要先说明边界:本次写作没有可引用的正文材料,也没有实际运行任何示例。文中涉及的平台具体数值(合法域名数量、超时上限、并发限制、是否要求备案等)待核实,请以对应平台官方文档为准;下面的代码均为未执行的示例,只示意结构,不作为可运行保证。
为什么两端不能共用同一套调用代码#
- 请求发起方不同。小程序端的请求经过宿主转发,没有浏览器那种同源策略,但需要在后台配置可访问的域名;H5 端由浏览器直接发出,跨域时浏览器会先发预检请求(OPTIONS),服务端不返回相应响应头就会被拦下。
- 凭证处理不同。H5 依赖 Cookie 时,需要前端设置
credentials、服务端返回对应的 CORS 响应头,且此时允许的来源不能写成通配符;小程序端不按浏览器的 Cookie 模型工作,鉴权更适合显式的请求头令牌。 - 可篡改性相同。小程序包可以被解包,H5 的 JS 对用户完全可见。两端都不能放第三方 API 密钥——这一点与站内此前关于密钥泄露的文章是同一个结论。
把第三方调用收进服务端出口#
推荐的结构是:小程序 / H5 → 自建接口(BFF,为前端聚合数据的中间层)→ 第三方 API。这样做换来四件事:
- 密钥只存在服务端,前端拿不到。
- 小程序后台只需配置自家域名,第三方域名变更不影响前端发版。
- 超时、重试、缓存、限流在一个地方统一,不必两端各写一遍。
- 第三方返回的字段变化,在服务端做一次映射,前端契约保持稳定。
代价是多一跳网络与服务端运维成本。如果第三方接口本身允许公开调用且无密钥,直连也可以,但仍建议保留服务端出口用于限流和缓存。
小程序侧:封装一层,而不是散落调用#
宿主提供的请求方法本身是回调式 API,建议包成 Promise,并把“网络失败”和“HTTP 非 2xx”分开,后续错误处理才有依据。
// 未执行示例:仅示意封装结构,BASE_URL 为占位
const BASE_URL = 'https://api.example.com';
function request(path, options = {}) {
return new Promise((resolve, reject) => {
wx.request({
url: BASE_URL + path,
method: options.method || 'GET',
data: options.data,
timeout: 10000, // 占位值,实际上限以平台文档为准
header: { 'content-type': 'application/json' },
success(res) {
if (res.statusCode >= 200 && res.statusCode < 300) {
resolve(res.data);
} else {
reject(Object.assign(new Error('HTTP ' + res.statusCode), {
kind: 'http',
status: res.statusCode
}));
}
},
fail(err) {
reject(Object.assign(new Error(err.errMsg || 'network error'), {
kind: 'network'
}));
}
});
});
}
H5 侧:超时要能真正中断请求#
浏览器端常见错误是只写了 Promise.race 超时,请求本身还在跑。用 AbortController 才能真正取消。
// 未执行示例:仅示意结构,API_BASE 为占位
const API_BASE = 'https://api.example.com';
async function request(path, { method = 'GET', body, timeout = 10000 } = {}) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeout);
try {
const res = await fetch(API_BASE + path, {
method,
headers: { 'content-type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
signal: controller.signal,
credentials: 'include' // 仅当确实需要携带 Cookie 时开启
});
if (!res.ok) {
throw Object.assign(new Error('HTTP ' + res.status), {
kind: 'http',
status: res.status
});
}
return await res.json();
} finally {
clearTimeout(timer);
}
}
上面开启 credentials: 'include' 后,服务端必须返回允许凭证的响应头,且允许来源不能是通配符,否则浏览器会直接拒绝——这是 CORS 的通用规则,具体配法依你的服务端框架而定。
错误分类与响应校验#
两端封装后,错误应至少分成四类,处理策略不同:
| 类别 | 典型来源 | 是否可重试 |
|---|---|---|
| network | 断网、DNS 失败、请求被中断 | 可,需退避 |
| timeout | 超过自设超时 | 视接口幂等性而定 |
| http | 4xx / 5xx | 4xx 一般不重试;5xx 有限重试 |
| business | HTTP 200 但业务码表示失败 | 不可自动重试 |
“HTTP 200 但业务失败”是第三方接口的常见形态,必须显式判断业务码,不能只看状态码。此外,JSON 解析成功也不代表结构正确,建议对关键字段做一次存在性与类型校验,失败时按 business 或单独一类处理,而不是让 undefined 漏到页面渲染层。
重试要有限度:只对幂等请求(查询类)自动重试,写操作交由用户确认或由服务端用幂等键保证唯一性。
本次无法确认的部分#
各平台对可配置域名数量、单次请求超时上限、并发请求数、上传体积的具体限制,本次没有材料支撑,不予列出,请查阅对应官方文档。同样,文中的 timeout: 10000 只是示例占位值,不代表任何平台的默认值或上限制。