小程序接口开发：别急着写代码

做小程序这几年，我接过不少“接口写好了但小程序跑不通”的活儿。打开代码一看，逻辑其实不复杂，问题往往出在最开始那一步：没想清楚接口到底该长什么样，就急着打开编辑器敲代码。今天这篇不聊框架选型，就聊聊小程序接口开发里那些真金白银换来的经验。

先定契约，再写实现

小程序端和后端是两拨人（或者同一个人的两种身份），最容易翻车的地方就是字段对不上。我的习惯是先花半小时把返回结构写死，哪怕只是写在注释里：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [],
    "hasMore": false
  }
}

别小看这个约定。code 用 0 表示成功还是用 200，分页是 page/size 还是 cursor，这些细节一旦定下来，后面联调能省掉一半扯皮。我见过太多项目，前端拿到 data.list 发现是 null，后端说“没数据我返回空对象”，然后两边开始互相甩锅。

登录态这块，坑最多

微信小程序的登录流程不算复杂，但细节多。我的做法是：wx.login 拿到 code 之后立刻换 openid，服务端生成自己的 token 返回，小程序存到 storage 里，之后每次请求带上。

这里有几个容易忽略的点：

• token 要有过期时间，但别设太短，用户用着用着被踢出去体验很差；
• 接口返回 401 时，小程序端要能自动重新登录并重试一次，而不是直接弹错误；
• 不要在小程序端存 session_key，那玩意儿是服务端用的，泄露了有风险。

还有个小细节：wx.login 的 code 只能用一次，五分钟过期。有些同学在 onLaunch 里调一次就以为万事大吉，结果用户切后台很久回来，token 过期了，整个页面白屏。加个请求拦截器，该续就续。

接口粒度：别太细，也别太粗

新手常犯的错是一个页面调五六个接口，每个接口就返回一两个字段。页面加载慢不说，还容易因为某个接口失败导致整个页面渲染不出来。

我的原则是按“页面”聚合。比如首页需要 banner、公告、推荐列表，那就做一个 /api/home/index，一次性返回。服务端内部怎么查是服务端的事，小程序端只关心一次请求拿到所有数据。当然也别走极端，把整个 App 的数据塞一个接口里，那样缓存和复用都做不了。

错误处理要统一

接口出错是常态，关键是让小程序端好处理。我一般约定：HTTP 状态码管传输层，业务 code 管逻辑层。网络断了、超时了，走 catch；业务失败了，看 code 给提示。

wx.request({
  url: baseUrl + '/api/order/list',
  header: { Authorization: token },
  success(res) {
    if (res.statusCode !== 200) {
      return handleNetworkError(res)
    }
    const { code, msg, data } = res.data
    if (code !== 0) {
      wx.showToast({ title: msg || '请求失败', icon: 'none' })
      return
    }
    renderList(data)
  },
  fail() {
    wx.showToast({ title: '网络不给力', icon: 'none' })
  }
})

把这段封装成一个 request 方法，页面里只写业务逻辑，代码会干净很多。

用云开发可以偷懒，但别偷错地方

如果是小项目、个人项目，云开发的云函数确实省事，不用自己搭服务器、配域名、搞备案。但要注意两点：一是云函数的冷启动，首次调用可能慢个一两秒，对体验敏感的接口最好做预热；二是数据库权限，别图省事全设成“所有用户可读”，用户数据该隔离就隔离。

另外云开发的调用次数和流量是计费的，接口设计得太碎，账单会让你肉疼。聚合查询、合理分页，这些基本功该做还得做。

最后说两句

小程序接口开发这件事，技术难度其实不高，难的是把边界想清楚：谁负责什么、失败怎么兜底、数据怎么流转。我现在的习惯是，动手前先在纸上画一遍请求链路，从用户点击到数据落库再回到页面，哪一步可能出问题，提前标出来。这半小时的投入，比事后 debug 三小时划算得多。

接口是两端之间的合同，写清楚比写快重要。