小程序开发规范：从代码到上线

做小程序这些年，我越来越觉得，真正拉开项目差距的不是某个炫酷功能，而是开发规范。规范到位，代码能维护、上线能稳定、交接能顺畅；规范缺失，项目越往后越像一团乱麻。知码客在邯郸服务本地客户的过程中，见过不少半路接手、返工重写的项目，问题大多出在规范上。今天就把我们团队在用的规范整理出来，供参考。

一、目录结构：先约定，再动手

小程序项目不大，但目录混乱同样致命。我们统一采用按业务模块划分的方式，而不是按文件类型堆在一起。

miniprogram/
  app.js
  app.json
  app.wxss
  pages/
    index/
    order/
      list.js
      list.json
      list.wxml
      list.wxss
  components/
    goods-card/
  utils/
    request.js
    format.js
  config/
    env.js

• 页面一律放在 pages 下，一个页面一个目录，四件套同名。
• 公共组件放 components，组件内部不直接调用全局接口，通过属性传入。
• 环境配置集中到 config/env.js，测试、预发、生产切换只改一处。

二、命名规范：让代码自己说话

命名是最容易被忽视的规范。我们约定：

• 文件名使用小写加中划线，如 order-detail.js。
• 变量与函数使用小驼峰，事件处理函数以 on 开头，如 onSubmitOrder。
• 常量全大写加下划线，如 MAX_PAGE_SIZE。
• 接口路径统一放在 utils/api.js，禁止在页面里硬编码 URL。

判断命名是否合格的标准很简单：三个月后别人接手，看名字能不能猜到用途。

三、代码分层：页面只做页面的事

很多小程序页面动辄上千行，逻辑、请求、格式化全堆在一起。我们的做法是三层拆分：

1. 页面层

只负责数据绑定、事件响应和跳转，不写复杂业务判断。

2. 服务层

把接口调用封装到 utils/request.js，统一处理 loading、错误提示、登录态失效重定向。

const request = (options) => {
  return new Promise((resolve, reject) => {
    wx.request({
      ...options,
      header: { Authorization: getToken(), ...options.header },
      success: (res) => {
        if (res.statusCode === 401) {
          wx.reLaunch({ url: '/pages/login/login' });
          return reject(res);
        }
        resolve(res.data);
      },
      fail: reject
    });
  });
};

3. 工具层

金额格式化、时间处理、校验函数统一放 utils，页面里直接引用，避免重复实现。

四、样式规范：别让页面各写各的

• 使用 rpx 做尺寸单位，设计稿按 750 宽度输出。
• 全局样式放 app.wxss，只放重置样式和通用类，业务样式留在页面内。
• 类名采用 BEM 思路，如 order-list__item--active，避免样式互相污染。
• 颜色、字号抽成变量，统一在 app.wxss 里定义，方便整体换肤。

五、性能与体验规范

规范不只是代码风格，还包括性能底线。我们要求：

• 首屏请求不超过三个，非关键数据延后加载。
• 长列表必须分页，单次不超过 20 条，配合 onReachBottom 加载更多。
• 图片统一走 CDN，列表图使用 lazy-load。
• 所有异步操作要有 loading 或骨架屏，避免用户以为卡死。
• 提交类按钮做防重复点击处理，防止重复下单。

六、提交与上线规范

代码提交前必须自查：

1. 本地跑通主流程，无控制台报错。
2. 敏感信息不写进代码，接口域名走配置。
3. 提交信息写清楚改动内容，如 feat: 订单列表增加状态筛选。
4. 上线前在体验版走一遍完整流程，确认版本号和描述。

在邯郸做小程序，客户往往更关心上线时间和后续维护。规范带来的直接好处是：需求变更时改动范围可控，出问题时定位更快。我们接过一个本地餐饮客户的旧项目，原代码没有分层、接口散落各处，一次简单的活动页改版花了三天；按规范重构后，同类需求半天就能交付。

规范不是束缚，而是让团队把精力放在业务上。如果你正在邯郸做小程序或 APP 开发，不妨先把这几条落地，后面会省下大量沟通和返工成本。知码客也会继续分享实际项目中的经验，用代码改变生活。