从零搭建第一个小程序

很多开发者第一次接触小程序时，会把注意力放在界面样式上，结果写到一半才发现数据没处放、登录流程走不通。这篇教程换一个顺序：先跑通一条完整的数据链路，再回头补界面。跟着做完，你会得到一个能注册、能记录、能读回数据的最小可用小程序。

一、先想清楚最小闭环

一个能称为「可用」的小程序，至少包含三件事：

• 用户身份：知道是谁在操作，哪怕只是匿名 openid。
• 数据读写：能把一条记录写进数据库，再查出来。
• 状态反馈：加载、成功、失败三种状态都有对应提示。

界面只需要两个页面：首页列表和新增表单。把这三件事跑通，后面加功能就是在这个骨架上长肉。

二、项目初始化与目录结构

在微信开发者工具里新建项目，选择不使用模板，得到基础结构后按下面的方式整理：

miniprogram/
  pages/
    index/        # 列表页
    create/       # 新增页
  utils/
    db.js         # 数据访问封装
  app.js
  app.json

把数据访问单独抽成模块，是为了让页面只关心「取数据、渲染、处理异常」，日后换存储方式时只改一个文件。

三、用云开发省掉后端

个人开发者最现实的选择是云开发：数据库、存储、云函数都在一个控制台里，不需要买服务器、配域名、备案。初始化只需在 app.js 里一行：

App({
  onLaunch() {
    wx.cloud.init({
      env: 'your-env-id',
      traceUser: true
    })
  }
})

环境 ID 在云开发控制台首页能看到。注意每个环境的数据是隔离的，测试环境和正式环境建议分开建。

四、封装数据层

直接在每个页面里写数据库调用，很快就会出现重复代码和分散的错误处理。先在 utils/db.js 里收口：

const COLLECTION = 'notes'

async function list() {
  const res = await wx.cloud.database()
    .collection(COLLECTION)
    .orderBy('createdAt', 'desc')
    .limit(20)
    .get()
  return res.data
}

async function create(text) {
  const res = await wx.cloud.database().collection(COLLECTION).add({
    data: {
      text,
      createdAt: Date.now()
    }
  })
  return res._id
}

module.exports = { list, create }

这里用 async/await 而不是回调，页面层的 try/catch 就能统一处理失败。云数据库默认权限是「仅创建者可读写」，个人项目直接用默认设置即可，省去写安全规则。

五、列表页的三种状态

页面数据里显式维护 loading、list、error 三个字段，渲染时按状态分支，避免出现「白屏但不知道发生了什么」：

Page({
  data: { loading: true, list: [], error: '' },

  onShow() {
    this.load()
  },

  async load() {
    this.setData({ loading: true, error: '' })
    try {
      const list = await db.list()
      this.setData({ list })
    } catch (e) {
      this.setData({ error: '加载失败，请下拉重试' })
    } finally {
      this.setData({ loading: false })
    }
  },

  onPullDownRefresh() {
    this.load().then(() => wx.stopPullDownRefresh())
  }
})

把加载逻辑放在 onShow 而不是 onLoad，新增页返回后列表会自动刷新，不需要页面间通信传参。

六、新增页与返回刷新

新增页只做一件事：拿到输入、调用 create、返回上一页。

Page({
  data: { text: '', submitting: false },

  onInput(e) {
    this.setData({ text: e.detail.value })
  },

  async submit() {
    const text = this.data.text.trim()
    if (!text) {
      wx.showToast({ title: '内容不能为空', icon: 'none' })
      return
    }
    this.setData({ submitting: true })
    try {
      await db.create(text)
      wx.navigateBack()
    } catch (e) {
      wx.showToast({ title: '保存失败', icon: 'none' })
    } finally {
      this.setData({ submitting: false })
    }
  }
})

submitting 字段用来禁用按钮，防止用户连点造成重复写入。这个细节在真实用户手里出现频率很高。

七、让首屏更快一点

• 列表接口加 limit，不要一次拉全量数据；数据多了改用分页或触底加载。
• 图片统一走云存储并加尺寸参数，避免原图直出。
• 页面数量少时，把公共样式和工具函数抽出来，减少重复下载。
• 首屏只渲染必要字段，详情放二级页面按需加载。

八、上线前的自查清单

1. app.json 里补全页面路径，确认没有遗漏注册的页面。
2. 云开发环境切换到正式环境，测试数据清空。
3. 填写小程序名称、类目、简介，类目与实际功能一致。
4. 在开发者工具里用「真机调试」跑一遍完整流程，重点看弱网下的提示。
5. 提交审核前，把测试用的入口和按钮隐藏或删除。

这套骨架不到两百行代码，但它包含了小程序开发里最常被忽略的部分：数据层的边界、页面状态的完整性、交互的防重复。把这三件事做扎实，后面无论是加搜索、加分类还是接入用户体系，都只是在这个结构上扩展，而不是推倒重来。