小程序开发规范实战指南

小程序项目做到第三个版本之后，真正拖慢进度的往往不是需求变更，而是没有统一规范导致的代码腐化：命名随意、目录混乱、样式互相覆盖、接口散落各处。本文从工程实践角度，整理一套可直接落地的小程序开发规范，适用于原生小程序与基于 uni-app、Taro 的跨端项目。

一、目录结构规范

目录结构应当在项目初始化时就固定下来，后续新增页面只做加法，不做结构调整。推荐按「页面 + 公共能力」两层划分：

├── pages/              # 页面，一个页面一个目录
│   ├── index/
│   │   ├── index.js
│   │   ├── index.json
│   │   ├── index.wxml
│   │   └── index.wxss
├── components/         # 自定义组件，按业务域再分子目录
├── utils/              # 纯函数工具，不依赖 wx API
├── services/           # 接口请求封装，按模块拆分
├── store/              # 全局状态
├── styles/             # 全局样式、变量、mixin
└── config/             # 环境配置、常量

几条硬性约定：

• 页面目录名使用小写短横线，如 order-detail，禁止中文与驼峰混用。
• utils 中只放无副作用的纯函数，任何 wx.request、wx.getStorage 调用都必须收敛到 services。
• 环境相关的域名、appId、开关配置统一放 config，禁止在业务代码里写死。

二、命名与代码风格

命名规范的价值在于降低阅读成本，团队内必须统一：

• 变量与函数使用小驼峰 getUserInfo，常量使用全大写下划线 MAX_RETRY_COUNT。
• 事件处理函数统一以 on 开头，如 onSubmit、onItemTap，与生命周期函数区分开。
• 布尔变量以 is、has、can 开头，避免 flag 这类无意义命名。
• 接口方法按「动词 + 名词」命名：getOrderList、createOrder、updateAddress。

建议接入 ESLint + Prettier，并在提交前通过 husky 做强制校验，把风格问题交给工具，而不是靠代码评审口头提醒。

三、WXML 与样式规范

WXML 中禁止写复杂表达式，逻辑一律前置到 JS 中计算：

<!-- 不推荐 -->
<view>{{ list.filter(i => i.status === 1).length }}</view>

<!-- 推荐 -->
<view>{{ activeCount }}</view>

样式方面有三条原则：

• 尺寸单位统一使用 rpx，字体大小可用 px 保证一致性。
• 页面样式必须加页面级前缀，如 .order-detail__title，避免全局污染。
• 颜色、间距、圆角抽成 CSS 变量放在 styles/variables.wxss，禁止散落魔法值。

四、数据请求与状态管理

请求层要做三件事：统一 baseURL、统一错误处理、统一 loading 控制。可以封装一个 request 方法，业务层只关心参数与返回值：

export function request({ url, method = 'GET', data = {}, loading = true }) {
  if (loading) wx.showLoading({ title: '加载中', mask: true });
  return new Promise((resolve, reject) => {
    wx.request({
      url: `${BASE_URL}${url}`,
      method,
      data,
      header: { Authorization: getToken() },
      success(res) {
        if (res.statusCode === 200 && res.data.code === 0) {
          resolve(res.data.data);
        } else {
          handleError(res.data);
          reject(res.data);
        }
      },
      fail: reject,
      complete() {
        if (loading) wx.hideLoading();
      }
    });
  });
}

状态管理遵循「能局部不全局」：页面内数据放 data，跨页面共享的用户信息、购物车等再放入全局 store，避免把所有状态塞进 getApp().globalData。

五、性能与上线规范

性能问题大多来自图片与 setData。规范上要求：

• 列表图片统一使用 CDN 并带尺寸参数，首屏图片开启 lazy-load。
• setData 只传变化字段，禁止整对象回写；长列表使用分页加载。
• 分包加载，主包控制在 2MB 以内，非首屏页面全部放入分包。
• 上线前检查 app.json 中的页面路径、域名白名单、隐私协议配置是否齐全。

规范的意义不是限制写法，而是让新成员在一天内能读懂项目结构，让每次迭代的改动范围可预期。

把以上几条沉淀成仓库里的 CONTRIBUTING.md 与 ESLint 配置，规范才算真正落地，否则只会停留在文档里。