唐山小程序开发：规范先行，少踩坑

在唐山做小程序这几年，见过太多项目不是死在需求上，而是死在“不规范”上。代码能跑，但没人敢改；接口能通，但换个环境就崩；上线三天，审核被拒两次。今天不聊虚的，就说说我在本地做项目时踩出来的那套开发规范，希望能帮到正在做小程序或者准备外包的你。

一、目录结构先定好，别让后来人骂娘

很多唐山本地客户找我接手二手项目，打开代码一看，pages 下面几十个文件夹平铺，utils 里混着业务逻辑，图片和字体文件散落各处。这种项目维护成本极高。我的习惯是固定一套结构：

├── pages/          # 页面，按业务模块二级分组
├── components/     # 公共组件，一个组件一个目录
├── utils/          # 纯函数工具，不引业务依赖
├── services/       # 接口请求封装，按模块拆分
├── store/          # 全局状态（用官方或轻量方案）
├── assets/         # 图片、字体，按类型再分
└── config/         # 环境配置、常量

别小看这一步。唐山做小程序的外包团队水平参差不齐，结构清晰的项目，换人接手成本能降一半。知码客接手的项目里，结构规范的，二次开发报价都能低一些，因为不用先花两天读代码。

二、命名与注释：给三个月后的自己留条路

• 文件名统一小写加中划线，比如 order-detail.js，别一会儿驼峰一会儿下划线。
• 组件名用大驼峰，页面路径用中划线，这是社区惯例，别自创。
• 接口函数命名带动作前缀：getOrderList、submitFeedback，一眼知道干啥。
• 注释只写“为什么”，不写“是什么”。比如“这里延迟 300ms 是因为安卓端键盘收起事件触发晚”，这种注释才有价值。

我在唐山给几家本地商户做小程序时，客户偶尔会问“你们代码别人能看懂吗”。说实话，规范写出来的代码，客户自己招个应届生都能改点小需求，这才是负责任的做法。

三、接口层必须收口，别在页面里直接 wx.request

这是最常见的坏味道。页面里到处 wx.request，域名写死，错误处理各写各的。规范做法是统一封装：

// services/request.js
const BASE_URL = config.env === 'prod' ? 'https://api.xxx.com' : 'https://test.xxx.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: getToken() },
      success(res) {
        if (res.statusCode === 200 && res.data.code === 0) {
          resolve(res.data.data);
        } else {
          handleError(res);
          reject(res.data);
        }
      },
      fail: reject
    });
  });
}

页面只调 services/order.js 里的方法，不关心域名和 token。这样换环境、加统一 loading、做错误上报，都只改一处。唐山小程序开发项目里，接口层收口做得好的，后期加埋点和监控特别顺。

四、样式规范：rpx 为主，少用行内样式

小程序屏幕适配用 rpx 是官方推荐，但别所有尺寸都无脑 rpx。字体大小、边框用 px 更稳，布局宽度用 rpx。另外，行内 style 尽量别写，一是难维护，二是动态样式多了性能也受影响。公共色值、间距抽成变量，放在 app.wxss 里，比如 --color-primary、--space-md。唐山做小程序经常遇到客户改主色调，有变量的话十分钟搞定，没有就得全局搜替换，容易漏。

五、提审前必查清单

规范不只是代码，还有上线流程。我整理了一份本地项目常用的自查清单：

1. 所有页面在真机（至少一台安卓、一台 iOS）跑一遍，重点看键盘弹起、下拉刷新。
2. 检查 app.json 里的页面路径有没有多余项，未使用的权限声明删掉。
3. 隐私协议、用户信息授权弹窗按最新要求配置，别等审核驳回再补。
4. 体验版加几个真实用户测，唐山本地客户我一般拉上店长和店员一起点，他们能发现我们想不到的操作路径。
5. 版本号、更新说明写清楚，方便回滚定位。

审核被拒最冤的一种情况：功能没问题，但类目选错。唐山做小程序的商户不少是餐饮、零售，选类目时对照官方文档，别凭感觉。

六、写在最后

规范这东西，短期看是束缚，长期看是保险。知码客在唐山做小程序和 APP 开发，接过的项目里，凡是前期把规范定下来的，后期需求变更、人员交接都从容得多。如果你正在唐山找团队做小程序，不妨在沟通时问一句“你们的目录结构和接口封装怎么定”，对方能说清楚，基本就靠谱一半。代码改变生活，先从让代码好维护开始。