小程序开发：怎样进行API接口对接

小程序 API 接口对接全流程

一 前置准备与域名配置

• 在微信公众平台 → 开发 → 开发设置 → 服务器域名中配置合法请求域名，必须使用HTTPS；仅配置过的域名才可被小程序发起请求。开发阶段可在开发者工具勾选不校验合法域名进行本地调试。小程序侧使用wx.request发起请求，浏览器式的CORS限制不适用，但仍需满足 HTTPS 与域名白名单要求。

二 服务端要求与接口约定

• 服务端需提供稳定可用的HTTPS接口，建议统一返回结构，例如：{ code, message, data }，并在文档中明确URL、方法、参数、鉴权方式、错误码。常见鉴权为Token（如 Bearer）放在请求头；如调用第三方 API，需先注册并获取 API Key。为提高可维护性，建议使用Swagger等规范编写接口文档并与前端约定版本与变更流程。

三 小程序端调用与数据处理

• 使用wx.request发起请求，处理成功与失败回调，结合wx.showLoading / wx.hideLoading优化体验，成功后用this.setData更新页面数据。示例（含加载提示与错误处理）：

// index.js
Page({
  data: { joke: '' },
  getJoke() {
    wx.showLoading({ title: '加载中...' })
    wx.request({
      url: 'https://v2.jokeapi.dev/joke/Any?type=single',
      method: 'GET',
      success: (res) => {
        if (res.statusCode === 200) {
          this.setData({ joke: res.data.joke })
        } else {
          wx.showToast({ title: '数据异常', icon: 'none' })
        }
      },
      fail: (err) => {
        wx.showToast({ title: '请求失败', icon: 'none' })
        console.error(err)
      },
      complete: () => { wx.hideLoading() }
    })
  }
})

• 如需展示列表数据，可在 WXML 中使用wx:for进行渲染：

<view wx:for="{{items}}" wx:key="id">
  <text>{{item.name}}</text>
</view>

• 涉及文件上传/下载时，使用wx.uploadFile / wx.downloadFile配合临时路径完成多媒体处理。

四 安全、性能与调试

• 安全：全链路使用HTTPS；登录后获取Token并在每次请求的Authorization头中携带；对用户输入进行合法性校验，对敏感数据加密传输；服务端应限流与鉴权，避免越权访问。
• 性能：对高频只读数据做本地缓存（如 wx.setStorageSync / wx.getStorageSync），减少重复请求；合并请求、分页/懒加载，必要时增加超时与重试策略。
• 调试：利用微信开发者工具查看请求与响应详情、设置断点；接口独立可用Postman先行验证；上线前关闭“不校验合法域名”，在多种网络与机型进行真机测试。

五 常见问题与排查清单

• 请求被拦截或提示不在合法域名：到公众平台检查服务器域名是否配置且为HTTPS；开发阶段可临时勾选“不校验合法域名”。
• 返回数据无法展示：确认接口statusCode为200，并按约定解析JSON；必要时打印 res 结构定位字段路径。
• 第三方 API 调用失败：核对API Key/Secret、请求参数与限流规则；注意第三方是否允许小程序域名调用。
• 网络错误或超时：增加fail/complete处理与用户提示，优化服务器性能或调整超时时间；必要时实现重试与降级。