唐山小程序接口开发：本地项目踩坑记

我是知码客，在唐山做小程序和 APP 开发这几年，接过的项目从路北区的餐饮点单，到丰南的工厂设备报修，再到曹妃甸的物流预约，几乎每个项目都绕不开同一件事：接口开发。前端页面做得再漂亮，接口一抖，用户该骂还是骂。今天不聊虚的，就把我在唐山本地项目里踩过的接口坑和对应做法摊开说说。

先想清楚：接口是给谁用的

很多唐山本地客户第一次做小程序，需求文档里写着“能下单、能支付、能看订单”，但没人提接口。等到开发时才发现，收银系统是本地服务商做的，会员数据在另一个 SaaS 里，小程序要同时对接三套东西。我的习惯是开工前先画一张数据流向图，把这几件事问清楚：

• 数据从哪来：自建后端、云开发数据库，还是第三方 SaaS 的开放接口
• 谁来鉴权：微信登录态、手机号验证，还是客户内部账号体系
• 失败怎么办：支付回调丢了、库存扣减超时，业务上能不能重试

这张图画完，接口清单基本就出来了。唐山不少做实体生意的老板对技术细节不熟，但你把“哪个环节会卡住用户”讲明白，沟通成本会低很多。

微信登录态，别自己造轮子

小程序接口开发里最基础也最容易出问题的就是登录。正确姿势是前端 wx.login 拿 code，后端换 openid 和 session_key，然后自己签发一个带过期时间的 token。这里有个细节：session_key 不能下发给前端，也别拿它当业务 token 用。

// 后端换取登录态（Node 示例，云函数里同样适用）
const res = await axios.get('https://api.weixin.qq.com/sns/jscode2session', {
  params: {
    appid: APPID,
    secret: SECRET,
    js_code: code,
    grant_type: 'authorization_code'
  }
});
const { openid, session_key } = res.data;
// 只把自定义 token 返回给前端，session_key 留在服务端
const token = signToken({ openid }, '7d');
return { token };

去年给唐山一家连锁烘焙店做会员小程序，他们之前找的外包把 openid 直接暴露在前端请求里，任何人改个参数就能查别人订单。这种问题不是技术难，是没把边界想清楚。

云开发还是自建服务，看项目体量

唐山做小程序的团队里，云开发用得不少，尤其是预算有限、周期紧的项目。我的判断标准很朴素：

• 日活几千以内、业务逻辑不复杂、没有存量系统要对接，云开发足够，省服务器和运维
• 要和本地 ERP、进销存打通，或者有复杂的定时任务和事务要求，老老实实自建后端

云开发的云函数写接口也有坑，比如数据库权限配置成“仅创建者可读写”后，管理端查全量数据就会失败；再比如云函数冷启动导致首屏接口慢，得靠预置并发或者前端做骨架屏兜底。这些细节在文档里都有，但真到项目里容易漏。

接口性能：唐山用户的网络现实

别默认用户都在 Wi-Fi 下。唐山周边县区的用户，移动网络信号波动是常态。接口层面能做的优化其实不复杂：

• 列表接口分页，单次返回不超过 20 条，字段只给前端要用的
• 把多个小请求合并成一个聚合接口，减少往返次数
• 高频只读数据加缓存，比如首页配置、分类树，缓存 5 分钟能挡掉大半请求
• 图片走 CDN，别让接口返回 base64

有个做本地生活服务的客户，首页原来串行发 6 个请求，首屏要两秒多。改成聚合接口加缓存后，压到 600ms 左右，用户投诉明显少了。

上线前的接口自查清单

每次交付前我都会过一遍这几条，唐山本地客户验收时也常拿这个当标准：

1. 所有接口都有统一的错误码和提示文案，前端不用猜
2. 支付回调做了幂等，重复通知不会重复发货
3. 敏感接口加了频率限制，防止被刷
4. 日志里能查到每次请求的 openid 和耗时
5. 正式环境和体验环境域名分开，别混用

接口开发没有玄学，把边界、异常和性能三件事想透，项目就稳了一大半。

我是知码客，专注小程序 / APP 开发，用代码改变生活。唐山本地的项目做多了会发现，技术方案大同小异，真正拉开差距的是对本地业务场景的理解——菜市场的称重逻辑、工厂的排班规则、门店的会员习惯，这些都得蹲在现场才摸得清。接口是骨架，业务才是血肉，两者对上，小程序才真正好用。