郑州小程序接口开发避坑实录

上周帮一位做社区团购的客户排查线上问题，他们的微信小程序在晚高峰下单时偶发「网络异常」，用户点了没反应，后台却收到两笔重复订单。查到最后不是业务逻辑的锅，是接口设计从一开始就没想清楚幂等怎么做。这类问题在郑州本地的小程序项目里我见得不少，今天就把接口开发中最容易翻车的几个点摊开聊聊，都是知码客这几年踩过的坑。

接口不是把数据吐给前端就完事

很多团队做小程序接口，习惯照着页面需求一页一页写：首页一个接口、详情一个接口、下单一个接口。上线后产品加个「猜你喜欢」，又得新开一个。接口越写越多，前端请求也越碎，首屏要发五六个请求，弱网环境下体验直接崩。我的建议是：按业务域划分，而不是按页面划分。

• 聚合接口：首页这种多数据源的场景，用一个接口返回主体结构，字段按需裁剪，前端少发请求，也少做拼装。
• 版本化：路径里带上 /v1/、/v2/，小程序发版有审核周期，老版本用户还在用旧接口，没有版本管理就是灾难。
• 统一响应结构：code、msg、data 三件套，错误码集中维护，别让前端去猜某个字段是 null 还是空数组。

登录态与鉴权，别自己造轮子

微信小程序的登录流程官方文档写得很清楚：wx.login 拿 code，后端换 openid 和 session_key，再签发自己的 token。但实际项目里常见两个问题：一是把 session_key 存到前端，二是 token 永不过期。前者等于把钥匙交给用户，后者等于用户手机丢了也没法踢下线。

// 后端签发 token 的简化示例（Node.js）
const token = jwt.sign(
  { openid, uid },
  process.env.JWT_SECRET,
  { expiresIn: '7d' }
);
// 前端每次请求带上 Authorization: Bearer xxx
// 后端中间件校验失败统一返回 401，前端静默重新登录一次

另外提醒一句，session_key 只应该待在服务端，用来解密手机号等敏感数据，任何情况下都不要下发到小程序端。

幂等和并发，晚高峰最容易出事

回到开头那个重复下单的案例。用户网络抖动，点击后请求超时，前端自动重试，两次请求都到了后端，库存扣了两次。解决办法不复杂：

• 前端生成一个唯一请求 ID（比如时间戳加随机串），放在 header 里。
• 后端用 Redis 做 SETNX，key 用业务类型加请求 ID，过期时间设几分钟，重复请求直接返回首次结果。
• 库存扣减用数据库乐观锁或 Redis 预扣，别用「先查再改」这种非原子操作。

郑州这边做餐饮、生鲜类小程序的客户多，午晚高峰流量集中，接口不做限流和幂等，出问题就是成片的客诉。我们给本地一家连锁餐饮做的排队取号接口，就是靠 Redis 令牌桶把瞬时并发压下来的。

性能优化从接口开始

小程序的体验分很大程度取决于接口响应速度。几个实际有效的做法：

1. 列表接口分页，单页别超过 20 条，图片走 CDN 并返回合适尺寸的 URL，别让前端拿原图。
2. 热点数据加缓存，但要注意缓存击穿，用互斥锁或逻辑过期。
3. 能并行的请求别串行，比如详情页的商品信息和评价列表可以同时发。
4. 开启云开发的云函数时注意冷启动，关键路径上的接口别全塞进云函数。

接口响应超过 1 秒，用户就会觉得「卡」；超过 3 秒，大概率直接退出。这不是玄学，是我们从多个项目埋点数据里看到的规律。

上线前该做的检查

接口开发完不算完，上线前建议过一遍清单：域名是否已配置到小程序后台的 request 合法域名、是否走 HTTPS、错误日志是否接入、敏感接口是否做了频率限制、压测过峰值 QPS 没有。这些事看着琐碎，但线上事故十有八九就出在这里。

我是知码客，在郑州做小程序和 APP 开发这些年，越来越觉得接口是项目的骨架，骨架歪了，界面做得再漂亮也撑不住。如果你正在郑州做小程序，或者手上的项目接口问题频出，欢迎来聊聊，很多坑其实提前一天想清楚就能避开。