石家庄小程序开发：规范先行少踩坑

在石家庄做小程序这几年，接过不少“救火”的活儿：有的项目代码一打开，页面逻辑和接口请求全糊在一个文件里；有的改个按钮颜色要翻三遍文档；还有的连基本目录结构都没有，换个人接手就得从头读一遍。说实话，小程序看着轻，规范不到位，后面全是隐形账单。今天就结合我们在石家庄本地的项目经历，聊聊小程序开发规范这件事，都是踩过坑之后攒下的经验。

为什么小项目更该讲规范

很多本地客户找到我们时，第一反应是“功能不多，先做出来再说”。这个想法能理解，但小程序的生命周期往往比预想的长：上线只是开始，后面还有活动页、会员体系、接口调整。规范不是给大厂准备的，恰恰是小团队省成本的手段。去年给裕华区一家连锁烘焙店做小程序定制开发，前期把目录和接口约定写清楚，后面加“门店自提”和“储值卡”两个模块，只用了原计划一半的时间。

目录结构：先分清楚谁管什么

我们内部有个约定，新项目第一件事是把骨架搭好，别急着写页面。一个相对通用的结构大致是这样：

miniprogram/
  pages/          // 页面，按业务模块再分子目录
  components/     // 通用组件，一个组件一个目录
  utils/          // 工具函数，按职责拆文件
  services/       // 接口请求，统一封装
  store/          // 全局状态
  styles/         // 公共样式变量
  config/         // 环境配置、常量

页面目录里只放页面自己的东西，公共组件一律进 components。别小看这一条，石家庄不少外包项目交付后维护困难，问题就出在“什么都往 pages 里塞”。

命名与代码风格：让接手的人少猜

• 页面、组件目录用小写加中划线，比如 order-detail，别用拼音缩写；
• 变量和函数用驼峰，事件处理函数统一以 on 开头，比如 onSubmitOrder；
• 接口函数按“动词+业务”命名，如 getShopList、createOrder；
• 提交前跑一遍 ESLint，格式化交给工具，别在代码风格上争论。

这些规则本身不复杂，难的是坚持。我们给每个项目配了统一的 lint 配置和提交前检查，新人进来照着写就行，不用靠口头传。

接口层：别让页面直接调 wx.request

这是最常见的问题。页面里到处写 wx.request，域名一换、登录态一加，就得全项目搜一遍。正确做法是统一封装请求层：

// services/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 && res.data.code === 0) {
          resolve(res.data.data)
        } else {
          reject(res.data)
        }
      },
      fail: reject
    })
  })
}

export default request

业务接口再按模块拆到 services/ 下，页面只关心拿到什么数据。这样以后换域名、加签名、做错误上报，都只改一个地方。

状态与数据：能少存就少存

小程序页面栈有限，全局状态别乱放。我们的习惯是：页面内数据放 data，跨页面共享的登录信息、用户资料放全局 store，缓存只存真正需要持久化的内容。曾经接手过一个石家庄本地商城的项目，购物车数据在三个页面各存一份，改一处漏两处，最后花了两天统一到 store 里才理顺。

上线前的检查清单

• 体验版走一遍主流程，真机测试别只看开发者工具；
• 检查分包配置，主包别超限，图片尽量走 CDN；
• 接口域名在小程序后台配好，别等提审才发现；
• 隐私协议、用户授权弹窗按最新要求补齐；
• 错误日志和关键埋点接上，上线后心里有数。

规范这东西，写出来像教条，用起来才知道值钱。知码客在石家庄做小程序和 APP 定制开发，一直信“知码识途、匠心铸客”——代码是写给用户看的，也是写给下一个维护的人看的。如果你正打算在石家庄做小程序，或者手里的项目已经有点乱，不妨先从目录和接口层动手，很多问题在规范落地的第一天就能少一半。