邯郸小程序开发：团队协作规范清单

在邯郸做小程序这几年，接过不少本地商家的项目，也帮几个同行收拾过烂摊子。说实话，很多问题不是技术难，而是开发过程中没规矩。今天不聊虚的，就把我在知码客踩过的坑和总结的规范列出来，给准备做小程序或者正在带团队的同行参考。

一、目录结构别随缘

见过最离谱的项目，页面文件全堆在根目录，命名从 a.js 到 zz.js。接手这种代码，改一个功能要翻半小时。我的习惯是按功能模块分：

pages/
  index/
  goods/
  order/
components/
  common-card/
  price-bar/
utils/
  request.js
  format.js
styles/
  variables.wxss

页面、组件、工具、样式各归各位。邯郸本地客户经常中途加需求，结构清晰的话，加一个页面就是复制粘贴的事，报价也好算。

二、命名统一，别中英混搭

• 页面路径用小写加中划线，比如 order-detail，别用 orderDetail 和 order_detail 混着来
• 组件名用大驼峰，文件用中划线，和官方示例保持一致
• 变量名别用拼音缩写，dd、hy 这种过两周自己都不认识

这条看着简单，但团队超过两个人就必须写进文档。之前给邯郸丛台区一个餐饮客户做点餐小程序，前后端联调时因为字段命名不一致，白白多花了一天。

三、接口层必须收口

最怕看到页面里直接 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: { token: wx.getStorageSync('token') },
      success(res) {
        if (res.statusCode === 200) resolve(res.data)
        else reject(res)
      },
      fail: reject
    })
  })
}

module.exports = { request }

好处是换域名、加签名、统一错误提示只改一处。邯郸不少商家后期要接自己的收银系统，接口收口了迁移成本低很多。

四、状态管理别过度设计

小项目用 getApp().globalData 就够了，别一上来就上复杂方案。但全局数据要有注释说明谁写谁读，不然三个月后没人敢动。页面内的数据尽量就近管理，跨页面共享的才放全局。

五、提交与评审

• 提交信息写清楚做了什么，别全是“修改”“更新”
• 每次提交只做一件事，方便回滚
• 上线前必须过一遍真机，开发者工具和真机差异不小，尤其安卓低端机

我们给邯郸本地客户交付前，都会在几台不同价位的安卓机上跑一遍，武安、峰峰那边的用户手机型号杂，这一步省不得。

六、文档和交接

规范的最后一条是写文档。README 里至少要有：环境要求、启动步骤、目录说明、接口列表、上线流程。知码客做小程序外包时，交付文档是写进合同的。不是较真，是邯郸本地很多客户后面会换维护方，文档齐全对谁都好。

规范不是为了好看，是为了让项目在半年后还能改得动。

以上这些，都是实际项目里磨出来的。如果你在邯郸做小程序或者 APP，正卡在团队协作或者代码交接上，欢迎来知码客聊聊，用代码改变生活这句话，我们是一直当真的。