小程序接口开发：石家庄本地项目的几个坑

做小程序这些年，我越来越觉得接口层是最能体现一个开发者水平的地方。页面画得再漂亮，接口一卡、一错、一超时，用户扭头就走。知码客在石家庄做小程序定制开发，接过的本地项目从餐饮外卖到社区团购、从工厂设备报修到本地生活服务，接口层踩过的坑能写满一个笔记本。今天挑几个有代表性的聊聊，都是实战里摔出来的经验。

一、别急着写业务，先把请求层收口

很多新手拿到需求就开始在每个页面里写 wx.request，写到最后你会发现：登录态过期没人处理、错误提示各写各的、域名换了要改几十个文件。我的习惯是先写一个统一的请求封装，所有业务接口都走它。

// utils/request.js
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') || ''
      },
      timeout: 10000,
      success(res) {
        if (res.statusCode === 401) {
          // 统一处理登录过期
          wx.removeStorageSync('token')
          wx.navigateTo({ url: '/pages/login/index' })
          return reject(new Error('登录已过期'))
        }
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data)
        } else {
          reject(res.data)
        }
      },
      fail(err) {
        reject(err)
      }
    })
  })
}

module.exports = { request }

这层封装看起来简单，但它决定了后面所有接口的维护成本。去年给石家庄桥西一家连锁烘焙店做会员小程序，门店多、活动多，接口改动频繁，正因为有这层收口，换域名、加签名、改超时时间都是改一处的事。

二、登录态与用户身份，别想当然

微信小程序的登录流程是 code 换 openid，但很多开发者忽略了两点：一是 code 只能用一次且五分钟过期，二是后端下发的 token 要有刷新机制。我在项目里通常让后端返回 access_token 加 refresh_token，前端在请求拦截里判断快过期就静默刷新，避免用户操作到一半被踢出去。

另外，石家庄本地不少客户是做线下门店的，同一个微信用户可能在多个门店消费，openid 是唯一的，但会员身份要按门店区分。这时候接口设计上就要把 store_id 作为业务参数传，而不是塞进 token 里，否则用户换门店就串数据了。

三、接口性能：小程序的耐心比你想的少

小程序首屏加载超过两秒，用户流失就很明显。接口层面能做的优化其实不少：

• 列表接口分页，别一次返回几百条，首屏给 10 到 20 条足够；
• 能合并的请求合并，比如首页的轮播、公告、推荐位，合成一个 home/init 接口，减少往返次数；
• 图片、静态配置走 CDN，接口只返回 URL；
• 对不常变的数据做本地缓存，用 wx.setStorageSync 加时间戳判断有效期。

之前给石家庄鹿泉一个工业园区做设备报修小程序，车间网络信号一般，我们把设备列表和常见故障类型做了本地缓存，用户断网也能先填单，联网后再补传，投诉率明显下降。这种细节，只有真正到现场看过的人才会想到。

四、错误码要成体系，别让前端猜

接口返回里最怕看到「系统错误」四个字。我的做法是和后端约定一套错误码：业务错误码用四位数，比如 1001 表示库存不足、1002 表示优惠券不可用，前端根据错误码做不同的提示和跳转。这样用户看到的是「该商品已售罄」，而不是一句冷冰冰的失败。

接口是前后端之间的契约，契约写得清楚，协作才不扯皮。知码客一直相信「知码识途、匠心铸客」，每一行代码都是和用户沟通的语言，接口返回的那句话，也是。

五、云开发场景下的接口思路

如果项目规模不大，云开发的云函数其实能省掉不少接口开发工作。石家庄很多中小商家的小程序，用云数据库加云函数就能跑起来，不用单独维护服务器。但要注意云函数的冷启动和并发限制，高频接口还是建议做缓存或者迁到自建服务。选型没有绝对的好坏，看项目体量和预算，这也是我们给本地客户做方案时反复权衡的地方。

写在最后

小程序接口开发这件事，技术本身不难，难的是把边界情况想全：网络断了怎么办、token 过期怎么办、后端返回脏数据怎么办。在石家庄做小程序开发，客户往往更看重稳定和实在，接口稳了，口碑才稳。如果你正在筹备自己的小程序项目，接口层多花一天时间设计，后面能省一周的返工。