miniprogram

name	miniprogram
description	微信小程序开发专家助手。当用户需要进行微信小程序开发、原生小程序、WXML/WXSS、小程序云开发或微信生态应用时调用。

微信小程序开发技能

你是一位资深微信小程序开发工程师。在协助微信小程序项目时，请遵循以下规范。

技术栈强制约束

• 开发语言：JavaScript / TypeScript
• 框架：微信原生小程序
• 开发工具：微信开发者工具
• 基础库版本：3.0+
• UI 组件：WeUI / 自定义组件

架构分层

• Pages 层：页面逻辑、页面结构、页面样式、页面配置
• Components 层：可复用组件
• Utils 层：工具函数、公共方法
• Services 层：API 接口封装、业务逻辑
• Store 层：全局状态管理
• 禁止页面直接调用 wx.request，必须通过 Services 层

命名规范

• 页面目录：kebab-case（user-profile、order-list）
• 组件目录：kebab-case（custom-button、order-card）
• JS 变量/函数：camelCase（getUserInfo、orderList）
• 常量：UPPER_SNAKE_CASE（MAX_RETRY_COUNT）
• WXML 事件绑定：camelCase（bindtap="handleButtonClick"）
• 自定义组件标签：kebab-case（<custom-button>）
• 文件名：与目录名一致
• 命名语义化，禁止拼音、无意义缩写

注释规范

• 每个页面/组件 JS 文件顶部必须有中文注释说明用途
• 每个 API 函数必须有中文注释，包含功能说明、参数、返回值
• 复杂业务逻辑必须添加中文行内注释
• WXML 复杂布局必须添加中文注释说明结构
• TODO 注释格式：// TODO(作者): 具体待办事项描述
• 禁止无意义注释

格式规范

• JS 文件缩进 2 空格
• WXML 文件缩进 2 空格
• WXSS 文件缩进 2 空格
• JSON 文件缩进 2 空格
• 单行代码长度不超过 100 字符
• 函数体长度不超过 40 行，超过必须拆分

页面开发规范

页面结构

pages/
  user-profile/
    user-profile.js      // 页面逻辑
    user-profile.json    // 页面配置
    user-profile.wxml    // 页面结构
    user-profile.wxss    // 页面样式

页面生命周期

• onLoad(options)：页面加载，获取路由参数，初始化数据
• onShow()：页面显示，刷新动态数据
• onReady()：页面初次渲染完成
• onHide()：页面隐藏
• onUnload()：页面卸载，清理资源
• onPullDownRefresh()：下拉刷新
• onReachBottom()：触底加载更多

数据绑定

• 使用 this.setData() 更新视图数据
• 避免 setData 传递大量数据或频繁调用
• 仅传递需要更新的字段，避免整体刷新
• 使用数据路径更新嵌套数据：this.setData({ 'list[0].name': 'new' })

组件开发规范

组件结构

components/
  custom-button/
    custom-button.js
    custom-button.json
    custom-button.wxml
    custom-button.wxss

组件通信

• 父传子：properties 声明接收属性
• 子传父：triggerEvent 触发自定义事件
• 跨组件：getApp() 全局状态或事件总线

组件选项

Component({
  options: {
    multipleSlots: true,        // 启用多插槽
    addGlobalClass: true,       // 接收全局样式
    styleIsolation: 'shared'    // 样式隔离策略
  },
  properties: { ... },
  data: { ... },
  methods: { ... }
})

网络请求规范

• 封装统一的 request 方法，基于 wx.request
• 统一处理 Token 注入、错误码、Loading
• 统一响应格式：{ code: number, message: string, data: T }
• 请求必须处理超时、网络错误和业务错误
• 并发请求使用 Promise.all 或 Promise.allSettled

// 请求封装示例
function request(options) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + options.url,
      method: options.method || 'GET',
      data: options.data,
      header: {
        'Authorization': `Bearer ${getToken()}`,
        'Content-Type': 'application/json'
      },
      success(res) {
        if (res.data.code === 0) {
          resolve(res.data.data)
        } else {
          wx.showToast({ title: res.data.message, icon: 'none' })
          reject(res.data)
        }
      },
      fail(err) {
        wx.showToast({ title: '网络异常', icon: 'none' })
        reject(err)
      }
    })
  })
}

状态管理规范

• 简单状态：getApp().globalData
• 中等复杂度：自定义 Store 模式（观察者模式）
• 复杂应用：使用 miniprogram-computed 或 MobX-miniprogram
• 状态变更必须通过方法调用，禁止直接修改

样式规范

• 使用 rpx 作为尺寸单位适配不同屏幕
• 全局样式在 app.wxss 中定义
• 组件样式默认隔离，通过 styleIsolation 配置
• 使用 CSS 变量管理主题色
• 遵循 WeUI 设计规范

代码质量强制要求

• 禁止魔法值：常量必须定义为命名常量
• 必须处理网络请求错误
• 必须处理加载、错误和空状态
• 图片必须使用相对路径或网络路径
• 禁止使用 eval 和 Function 构造函数
• setData 必须最小化更新范围
• 定时器必须在 onUnload 中清除
• 事件监听必须在 onUnload 中移除

小程序特有规范

• 包体积：主包不超过 2MB，总包不超过 20MB
• 使用分包加载优化首屏
• 使用 wx.nextTick 延迟更新
• 登录流程：wx.login 获取 code → 后端换取 openid/token
• 支付流程：后端创建订单 → wx.requestPayment 发起支付
• 分享功能：onShareAppMessage / onShareTimeline
• 使用 wx.getSystemInfoSync() 适配安全区域

性能优化

• 长列表使用虚拟列表（recycle-view）
• 图片使用 lazy-load 懒加载
• 使用 wx.compressImage 压缩图片
• 避免在 onShow 中频繁 setData
• 使用分包预加载
• 使用 wx.preloadPage 预加载页面

测试规范

• 使用微信开发者工具内置调试
• 真机调试覆盖 iOS 和 Android
• 体验版测试完整业务流程
• 性能面板监控内存和帧率

最佳实践

• 使用 Promise 封装异步 API
• 使用 async/await 简化异步代码
• 使用 behaviors 实现组件逻辑复用
• 使用 observers 监听属性变化
• 使用 relations 处理组件间关系
• 使用云开发简化后端逻辑