小程序接口开发：从设计到上线

我是知码客，在邯郸做小程序和 APP 开发。这几年接过的项目里，接口层往往是决定交付质量的关键：页面做得再漂亮，接口一乱，后期改需求、加功能、排查线上问题都会变得很痛苦。这篇文章聊聊小程序接口开发中我实际在用的做法，从设计、鉴权到上线后的维护。

先定接口契约，再写页面

很多团队的习惯是先做界面，边做边补接口，结果前端等后端、后端猜字段。我的做法是先和客户把业务流程走一遍，把接口清单和字段定下来，形成一份简单的契约文档，再并行开发。

• 按业务域划分接口前缀，比如 /api/order、/api/user，避免所有接口堆在一个文件里。
• 统一响应结构，code、message、data 三层，前端只写一次拦截逻辑。
• 分页参数统一为 page、pageSize，返回统一带 total。
• 时间统一用时间戳或 ISO 字符串，不要一边用字符串一边用数字。

邯郸本地不少客户是餐饮、零售、本地服务类商家，业务变化快，接口契约提前定好，后面加个优惠券、加个门店自提，改动范围就可控。

登录态与鉴权

微信小程序的登录链路是固定的：wx.login 拿 code，后端换 openid 和 session_key，再签发自己的 token。这里有几个容易忽略的点。

// 前端登录后统一带上 token
const request = (options) => {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'content-type': 'application/json',
        'Authorization': 'Bearer ' + wx.getStorageSync('token')
      },
      success: (res) => {
        if (res.data.code === 401) {
          // token 过期，重新登录后再重试一次
          return relogin().then(() => request(options)).then(resolve).catch(reject);
        }
        resolve(res.data);
      },
      fail: reject
    });
  });
};

• token 设置合理有效期，配合刷新机制，不要用永久 token。
• 敏感接口做二次校验，比如支付、提现，不能只靠前端判断。
• session_key 只在服务端使用，绝不下发到小程序端。

用云开发还是自建服务

选型要看项目体量。轻量工具类、活动报名、预约类小程序，云开发的云函数加云数据库能省掉服务器运维，上线快，适合预算有限、需要快速验证的商家。涉及复杂事务、对接第三方系统、数据量大的项目，还是自建后端更稳。

在邯郸接触的客户中，本地生活服务类项目用云开发的不少，成本低、迭代快；而连锁门店、需要和已有 ERP 打通的，基本都选自建服务。选型没有绝对对错，关键是和客户的实际运营节奏匹配。

接口性能与稳定性

• 列表接口一定要分页，并且给数据库字段建索引，别等数据涨起来再补。
• 高频读取的数据加缓存，比如首页配置、门店信息，减少数据库压力。
• 第三方接口（支付、地图、短信）统一封装，加超时和重试，失败要有兜底提示。
• 接口日志记录请求参数和耗时，线上出问题时能快速定位。

上线前的检查清单

接口开发完不等于结束。上线前我会过一遍：域名是否已在小程序后台配置、HTTPS 证书是否有效、生产环境和测试环境配置是否分离、错误码是否覆盖常见场景、是否有接口监控。小程序上线后，接口的兼容性也要注意，老版本小程序可能还在调用旧接口，字段不要随意删除，先加新字段再逐步下线。

接口是小程序和 APP 的骨架，前期多花一点时间把结构定清楚，后面的维护成本会低很多。我是知码客，专注小程序和 APP 开发，用代码改变生活，也欢迎邯郸本地的朋友一起交流项目里的具体问题。