邯郸小程序接口开发避坑实录

上周帮邯郸丛台区一个做社区团购的客户收拾了个烂摊子。项目是去年找外地团队做的，界面看着还行，但一到下单高峰期就卡死，团长在群里骂、客户在群里退。我打开代码一看，接口这块几乎是裸奔——没有分页、没有缓存、一个请求查八张表。这种问题在邯郸本地的小程序项目里太常见了，今天就把接口开发这块踩过的坑捋一捋，都是真金白银换来的经验。

接口不是能返回数据就行

很多外包团队交付的标准是「页面能点、数据能出来」，至于接口设计得怎么样，客户自己也看不懂。等业务量上来，问题全暴露。我在知码客接手的本地项目里，接口层面最常见的三个毛病：

• 列表接口不分页。商品、订单、会员全量返回，前期几十条数据跑得飞快，商家搞一次促销直接几百条，小程序端渲染卡顿，用户以为死机了。
• N+1 查询。订单列表里循环查用户头像、商品图，一条订单三次数据库往返，50 条订单就是 150 次，云开发的按量计费模式下这就是在烧钱。
• 没有统一的错误码。前端拿到 500 只能弹「网络异常」，用户不知道是没登录、库存不足还是重复提交，客服电话全打到老板手机上。

邯郸本地场景下的接口设计要点

1. 列表接口默认带分页

不管现在数据量多小，列表接口一律上分页。云开发用 skip + limit，自建后端用游标分页更稳。给个云函数的写法：

// 云函数：getOrderList
const cloud = require('wx-server-sdk')
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })
const db = cloud.database()

exports.main = async (event) => {
  const { page = 1, size = 10, status } = event
  const where = { openid: event.openid }
  if (status) where.status = status

  const countRes = await db.collection('orders').where(where).count()
  const listRes = await db.collection('orders')
    .where(where)
    .orderBy('createTime', 'desc')
    .skip((page - 1) * size)
    .limit(size)
    .get()

  return {
    code: 0,
    data: { list: listRes.data, total: countRes.total, page, size }
  }
}

注意 size 要做上限校验，别让前端传个 1000 把数据库拖垮。

2. 高频数据加缓存

邯郸很多本地商家做的是到店自提、社区团购这类生意，商品分类、门店信息、营业时间这些数据一天改不了几次，但每次打开小程序都要查。云开发可以用 collection.watch 或者干脆在云函数里做内存缓存，自建后端就上 Redis。一个分类接口从 80ms 降到 5ms，用户体感差别很大。

3. 写接口必须做幂等

下单、支付回调、核销这几个接口，用户手抖点两下、微信回调重试，都会重复触发。我一般让前端带一个 requestId，服务端用唯一索引或者先查后写来兜底。邯郸有家做餐饮的客户，之前就因为核销接口没做幂等，一张券被核了三次，月底对账对到半夜。

接口联调阶段的几个土办法

跟本地客户合作，很多老板不懂技术，但特别在意进度。我的做法是：

1. 接口文档用 Apifox 或 YAPI 维护，每个接口写清楚入参、出参、错误码，链接直接发客户微信群，谁都能点开看。
2. 开发环境做一个「模拟数据开关」，前端不依赖后端进度，页面先跑起来给客户看效果。
3. 上线前用云开发的日志或者自建后端的 access log 跑一遍压测，重点看慢查询。

接口这活儿，做的时候多花两天，后面能省两个月。省下的不是开发时间，是客户的信任。

说点实在的

在邯郸做小程序，客户预算普遍不像一线城市那么宽裕，但这不代表接口可以糊弄。相反，正因为预算有限，才更要把钱花在刀刃上——把接口做扎实，后期改需求、加功能都轻松；接口一团乱麻，改个小功能都要推倒重来，那才是真的贵。

我是知码客，在邯郸做小程序和 APP 开发，接过的项目里有社区团购、本地生活、企业展示，也有几个从外地团队手里接过来救火的。如果你手上有项目卡在接口这块，或者正准备做小程序想避避坑，欢迎聊聊。代码这东西，写的时候用心，用的时候才省心。