小程序接口开发实战指南

小程序接口开发是整个项目里最容易被低估的部分。页面写得再漂亮，接口一乱，后期维护和扩展都会变成灾难。这篇文章从实际项目出发，聊聊小程序接口开发中值得认真对待的几件事。

先定协议，再写代码

很多项目一上来就写 wx.request，结果每个页面各自拼 URL、各自处理错误，最后代码里散落着几十种返回格式。建议在动手前先把接口约定固定下来：

• 统一返回结构，例如 { code, message, data }，业务成功用 code === 0 判断；
• 统一错误码区间，比如 1xxx 表示参数错误、2xxx 表示鉴权失败、5xxx 表示服务端异常；
• 分页参数统一为 page 与 pageSize，返回里带 total 与 hasMore；
• 时间字段统一用时间戳或 ISO 字符串，不要混用。

协议定好之后，前端封装一个请求层，页面只关心业务数据，不再重复处理 loading、错误提示和登录态。

封装请求层：把重复逻辑收口

小程序的 wx.request 是回调风格，直接在每个页面调用会非常啰嗦。用 Promise 包一层，再叠加拦截逻辑，是最常见的做法：

const BASE_URL = 'https://api.example.com';

function 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': wx.getStorageSync('token') || ''
      },
      success(res) {
        const body = res.data;
        if (res.statusCode === 401 || body.code === 2001) {
          // 登录态失效，跳转登录
          wx.navigateTo({ url: '/pages/login/index' });
          reject(body);
          return;
        }
        if (body.code === 0) {
          resolve(body.data);
        } else {
          wx.showToast({ title: body.message || '请求失败', icon: 'none' });
          reject(body);
        }
      },
      fail(err) {
        wx.showToast({ title: '网络异常', icon: 'none' });
        reject(err);
      }
    });
  });
}

module.exports = { request };

这一层还能继续加东西：请求重试、并发控制、日志上报、mock 开关。关键是所有页面共用同一份逻辑，改一处全局生效。

登录态与接口鉴权

小程序登录流程是固定的：wx.login 拿 code，后端换 openid 和 session_key，再签发自己的 token 返回给前端。接口开发时要注意几点：

• token 存 wx.setStorageSync，请求头统一携带，不要放在 query 里；
• token 过期要有静默刷新机制，避免用户操作到一半被踢回登录页；
• 敏感接口（支付、手机号解密）必须在服务端二次校验，不能只信前端传参；
• 服务端用 openid 作为用户唯一标识，不要用前端传来的 userId。

云开发场景下的接口写法

如果项目用云开发，接口层会变成云函数加数据库调用。此时同样建议做一层封装，把集合名、权限判断、返回结构收口：

// cloudfunctions/order/index.js
exports.main = async (event, context) => {
  const { action, payload } = event;
  const { OPENID } = cloud.getWXContext();

  switch (action) {
    case 'create':
      return createOrder(OPENID, payload);
    case 'list':
      return listOrders(OPENID, payload);
    default:
      return { code: 1001, message: '未知操作' };
  }
};

async function createOrder(openid, payload) {
  const db = cloud.database();
  const res = await db.collection('orders').add({
    data: { ...payload, openid, createdAt: Date.now() }
  });
  return { code: 0, data: { id: res._id } };
}

云函数里用 action 做路由，比每个功能建一个云函数更好管理，也减少冷启动次数。数据库权限记得设成“仅创建者可读写”，不要图省事开成所有人可读。

性能与稳定性

接口开发不只是“能通”，还要考虑真实网络环境：

• 合并请求：首页多个模块的数据尽量用一个聚合接口返回，减少请求数；
• 列表分页：首屏控制在 10 到 20 条，滚动加载而不是一次拉全量；
• 缓存策略：不常变的数据（配置、分类）本地缓存加过期时间，减少重复请求；
• 超时与降级：设置合理超时，失败时给用户可重试的入口，而不是白屏；
• 接口监控：记录慢接口和错误率，上线后才知道哪里真的有问题。

写在最后

小程序接口开发的本质是把前后端协作的规则定清楚，再用一层薄封装把重复劳动消掉。协议统一、请求层收口、鉴权可靠、性能可控，这四件事做到位，项目规模变大时也不会失控。前期多花半天设计，后期能省下大量排查时间。