AI开发微信小程序的实践笔记

作者

1. 综述

1.1 出发点

近期在 Codex 和 Claude Code 指导和协助下做了一款熟人间的点餐微信小程序。

应用范围仅限公司内的熟人圈子（有同事的家人为了让同事吃上健康餐，同时制作更多份邀请大家陪吃）

之前是通过群接龙的+手动整理需求制作+手动统计收款 的方式。但有一些问题和不足：

  1. 群接龙在多人同时操作时（删除+修改+新增）偶尔会出错
  2. 手动整理需求，打印标签，统计订单的个性化要求比较麻烦
  3. 手动统计收款也很麻烦

1.2 核心功能设计

基于上面的问题，考虑做一个小型的小程序。定制化为这个事情提供服务支持。

首先要想清楚核心需求（可以通过和 AI 讨论想清楚），至少满足一些核心需求，比如：

1. 管理员可以在小程序中发布餐次，包括：餐的描述、基础价格、可选项信息、图片（可选）、数量限制等。
2. 用户可以针对管理员发布的餐次进行订餐，订餐的时候可以根据喜好选择可选项
3. 管理员可以方便地导出餐次信息为 xlsx 之类的表格，帮助制作
    - 统计基础餐份数
    - 统计各可选项份数
    - 得到各个用户订单的打印标签(方便快速打印粘在餐盒上)
4. 管理员可以在特定时候完成收款和结算操作
    - 方便地统计各个用户的待付款总额，指导群收款（微信小程序的个人版不支持付款接口）
5. 由于需要区分管理员和用户身份，所以需要一套简单的身份权限系统
    - 区分管理员/用户
    - 且管理员可以修改其他管理员的身份（更正式的项目一般有超级管理员身份，这里简化）
6. 由于微信小程序只能知道用户的 openid ，不能直接获取用户的微信昵称，但群收款需要能对应
    - 所以需要注册（主要就是设置昵称）和改昵称的功能
7. 由于不希望陌生人和恶意用户下单，所以需要封禁功能，和新用户状态设置功能
    - 管理员可以 启用/禁用 特定用户，禁用后无法下单
    - 管理员可以设置 新注册用户的状态默认为 启用/禁用
8. 同时为了审计/追溯方便，需要有较完善的日志记录，特别是针对待付款变化的日志记录：
    - 下单/撤单 的操作日志，以及操作前后待付款变化。
    - 收款/增加待付款 等操作的日志，以及操作前后的待付款变化。
    - 管理员发布/锁定/完成/取消 餐次的日志。方便追溯完整的故事。
    - 身份改变日志。方便追溯完整的故事。
    - 注册/禁用/启用 改变日志。方便追溯完整的故事。
9. 可选的扩展功能
    - APP图库管理(上传/修改/删除)，并支持给每个餐次选配一个图
    - 订单留言/备注
    - 批量下单
    - 用户的订单整合管理页面

1.3 工程规模

完成后的当前版本，用 cloc 统计项目：

  • 忽略注释和空行，服务端代码有大约 1.3 万行
  • 忽略注释和空行，前端代码有大约 2.2 万行
  • 忽略空行，文档有大约 0.85 万行

其中代码基本完全由 Codex + Claude Code 完成。

我主要花时间于文档部分

  • 先提潦草的需求，再让 Codex 基于我的需求并结合工程目前的情况下细化下来的，我再 Review。

整体上可能花了15-20 小时左右完成，其中

  • 40% 时间是在和 AI 调文档。
  • 60% 的时间在调试和让 AI 改bug 和优化。

1.4 经验收获

此次前我

  1. 还没有 申请/开发/发布过微信小程序
  2. 没写过 JS 等前端代码
  3. 没用过 python 的 fastapi 等服务框架
  4. 也没自己完整实践过项目的版本管理
    • 包括dev版本到release版本的build部署
    • 版本升级兼容等等

这些领域都在此次实践中得到了一些熟悉。所以此次实践还是学习了不少。

并且这次靠 ChatGPT + Codex + Claude Code 让我工程和学习的效率都高了非常多。

1.5 Github 工程

https://github.com/Raytto/ganghaofan_public

  • 注：要运行的话，里面环境变量等配置需要更换为你的（可以让 AI 搞，更快）。

下面，记录完整实践流程的关键部分的笔记。

2. 小程序申请备案

小程序开发前要先再微信开放平台注册小程序，才能获得 AppID 等信息，进而能在微信开发者工具中开发。

微信开放平台地址：https://open.weixin.qq.com

在微信开放平台新建一个小程序并跟随引导设置小程序名字、图标、邮箱、备案信息等。

如果是个人账户（我这次这种）申请的小程序则不允许涵盖经营相关内容，也不支持支付等接口。

且个人账户的小程序在备案时需要说明清楚用途和经营无关（我为此备案失败了三次）。

整体而言备案可能花费的时间会较长，可以前置于实际的开发前先备案，并行开发。

3. 微信开发者工具

微信小程序看起来比较接近网站开发。但实际用到的渲染引擎、视图层语言（WXML + WXSS），路由机制，运行环境等都和面向浏览器的网站不同。

所以需要专门安装微信开发者工具，才能调试。（开发可以用vscode、或者纯命令行 AI 都行）

下载微信开发者工具，用微信号登录，AppID处应该可以直接选择上一步创建的 App 的 ID

前端架构由于计划用 AI 开发，建议用尽量基础一点的架构（训练数据更充分），即 JS-基础模板，可以减少一些 bug 的可能性。

创建后目录下会自动创建一版基础的微信小程序工程结构。

4. 工程结构

由于我们希望尽量用 AI 来开发，肯定是希望 AI 能同时负责前端和后端，且能提升开发效率（如遇见 bug 先检查前端代码，没问题就自动继续检查后端），否则我们还要扮演联调过程的通信者。

所以我们可以把客户端工程目录 client, 服务器工程目录 server, 文档目录 doc 放在同一个大工程文件夹下。

这样无论使用 Claude Code、Codex、Gemini Cli、Copilot 都可以直接在大文件夹下操作，更加方便。

4.1 文档 doc

参考 SPEC AI 开发工作流，即先有 Specification Document 再基于此文档开发，个人体验在现阶段 AI 开发效果还是蛮好的。个人体验优势如下：

4.1.1 SPEC 优势1：文档化厘清自己的需求。

将脑海中的想法清晰表达出来，并不是一件自然而然或者轻松的事情，是需要付出一些努力的，文档化就是在帮助自己完整表达。

甚至更多的时候，脑海想法本身都是模糊的，更需要通过文档（也可以结合其他比如草图之类的方法），让自己的想法一点点完善起来。

对想法有了 好的/结构化/精确的 需求描述，AI 执行的结果才更可预期。

4.1.2 SPEC 优势2：高效把控 AI 开发结果

目前实践下来 Codex、Claude Code 在听话方面整体表现还是不错的（有些复杂的需求有时会只做一半，但偏离一般不多，通常也仅在细节上，后期很好改）

但前提是指令是明确且充分受把控的。就算 AI 再厉害，没交待清楚他做出来的东西可能和需求也差别很大。其实类似老板给员工沟通任务

所以把控住 SPEC 文档，在 AI 较为厉害的情况下（ Codex 和 Claude Code 算较厉害了），也就把控住了后面 90% 的 AI开发。

且相比于 AI 开发以后去各个代码文件里分析函数引用关系，慢慢阅读代码而言，阅读 SPEC 显然就轻松高效了太多。

4.1.3 SPEC 优势3：AI 协助高效写 SPEC

在团队开发中，写 SPEC 文档本身确实也是一件不太轻松的事情。

不过现在有了 AI 本身可以帮助我们写 SPEC （进一步让AI扮演产品经理角色），效率则更进一步

具体而言，比如对于一个 feature 可以先写一个简单的需求，表达清楚自己暂时想到的想要的东西。

4.1.3.1 （例）日历页面的翻页功能的草稿需求:

日历页面的翻页功能
当前问题：日历页面仅能看到12天，如果想提前发出餐次或者提前很多天下单都做不到
考虑修改：
- 添加分页逻辑，默认页是从当下的昨天，到当下之后的第12天，一共14天，即两周
- 日历的顶部可能有一个可点击的按钮，文本为“两周前”点击后相对于当前分页的日期整体往前14天，刷新整页
- 日历底部有一个可点击的按钮，文本为“两周后”，点击后相对当前分页的日期整体往后14天，刷新整页
- 设计一下这两个按钮样式，尽量和页面搭配一点，好看一点
- 可以尝试顶部的“两周前”按钮默认看不到，需要往下拉，滑动后才能看到，即默认进入日历页面时滑动位置在此按钮以后
基于以上需求先写此feature 的 SPEC 文档。先不要改代码

要求 AI 去基于此写 SPEC（我一般写 SPEC 喜欢用 Codex：感觉Codex 更擅长设计，且可以云端处理需求，且可以手机提需求，就很方便）

AI 写完以后要看一看 AI 写的 SPEC 文档。

个人建议：如果想对项目更有把控力，尽量要有能力搞懂文档提到的所有内容，如果不懂则没办法把控。其实 AI 时代想搞懂这些也不难，问 AI 就行，慢慢学。

4.1.3.2 （例）日历页面的翻页功能的 SPEC 修改反馈:

AI 写的 SPEC 经常会有一些细节非我们预期的。比如歪曲、更常见的是添加很多没必要的逻辑、以及 AI 对于有些实现会直接在 SPEC 中写两套方案。对于这些我们需要进一步对 SPEC 进行修改。

  • 可以自己手动修改 SPEC，适合改一些小细节，或者删一些没必要的内容
  • 也可以把想修改的内容列成 list 丢给 AI 来修改（更像老板和产品经理开会对方案）
- 图库管理面不显示图片有效标记为否的图
- 已失效/已删除的图片 不要有恢复功能
- 图库页面可以选择一张图其作为默认图（可能存在 system settings?存一下默认图的 id），默认图在图库页面有个标记。删除默认图，自动找一个最新的且还生效的图作为默认图。要考虑图库不存在任意有效图片的情况（各个列表选项内容处提示“无”，图片用纯灰之类的占位都行）
- 餐次、订单创建、订单展示页面如果发现当前餐次的图片失效/或没有文件/图片ID不存在，则展示默认图
- 创建餐次时默认选择默认图
- 图片展示时统一剪切到16:9比例（受前端控制）
- 不用统计图片的引用次数

对于一些复杂的需求， SPEC 可能需要修改多轮。

SPEC 确定没问题，再让 AI 实际去根据 SPEC 开发和测试（不过由于是微信小程序，目前 AI 仅方便对后端逻辑进行测试，前端需要手动来）。

4.2 客户端 client

文件夹下直接对应着微信小程序工程

工程下比较重点的就是 pages 目录，每个页面会对应一个 pages 下的文件夹。每个页面会包含 js, json, wxml, wxss 四个文件。

4.3 服务器 server

server 下则对应着服务器工程。

5. 使用 AI 开发

由于 Claude Code 对中国封锁非常严，要在国内使用需要比较强的梯子，但我自己尝试失败了。

我目前使用的方式是直接用在美国的云服务器来远程控制开发（vscode ssh 远程开发倒是非常方便）。

且我尝试过阿里云的美国服务器，发现依旧用不了（openai 和 claude 都是），应该是专门针对阿里云服务器做了屏蔽。

Google Cloud , AWS , Azure 这些应该可以用，但价格都不便宜（即使首年有免费额度，但总是时间有限）

个人暂时找了个国内不知名的小云服务器商，非凡云，可能是比较小，没上 Claude 和 Openai 的封锁名单

如果没有合适的方式，也可以尝试我这种方法。

我的非凡云邀请链接：https://sso.ffy.com/sign-up?invite_code=PZkF8tgNkv

在云服务器上开发以后用 github 或者其他方式把前端工程同步到 windows 机器上用微信开发者工具调试前端。

5.1 Codex

个人最喜欢 codex 的特色是 云开发 ：

  1. 不限场所：随时随地可以用手机提需求。
  2. 离线等待：提了 需求/bug修改 以后就在云端执行了，过程中不用等上一个任务结束，就可以立刻提下一个需求（不过要考虑冲突，尽量让需求独立）

除此以外，Codex 也擅长文档撰写和UI设计（相对于 Claude Code 而言）

且 Codex 对我还有一大好处： 仅需 ChatGPT plus 就可以用。

而 ChatGPT plus 对我而言，即使没有 Codex 也已经是刚需，所以相当于是没有额外付费。

5.2 Claude Code

Claude Code 的执行力非常强，其 todolist 管理也使其可以负责一些多步的复杂任务，且整体速度比较快（相对于 Codex）。

个人体验，其很擅长高效改 bug，调环境等等执行工作。

有时我会把重启服务器、停止服务器、装环境之类的杂活也交给 claude code。

5.3 Codex + Claude Code + vscode

在此次实践中我把 Codex 和 Claude Code 结合起来在 vscode （ssh 远程控制）中使用。

  • vscode ssh 远程开发非常方便。
  • 特别是用美国服务器，能让 claude code 和 codex 稳定使用。
  • 远程开发环境只用部署一次，从不同的电脑远程控制都直接可用。
  • codex 和 claude code 的对任务历史也自动同步（毕竟实际一台机器）。
  • Linux 环境，可以和正式服一致，避免一些环境问题，但同时又能用 windows 电脑方便操作。

Codex 和 Claude Code 可以并行工作，同时执行任务（比如改 bug、改优化、写文档）。甚至有更多并行需求的话，还可以多个 terminal 开 claude code cli 并行。

下面介绍一些个人常用的 AI 开发场景

5.3.1 场景1：写一个新的 feature 或者从零搭项目

  1. （手动）先自己写一个需求描述，可文档可一段文本，需求格式可以很随意，但要尽量说清楚原因（帮助AI了解出发点和上下文，以更好地设计）核心需求、要求等等。
  2. （Codex）要求 Codex 基于上面的文档进行需求细化，并补全核心设计，最后落地为一个 SPEC 文档
  3. （Codex）阅读 SPEC 文档，手动/或列出修改意见给codex 修改 SPEC 文档，直到 SPEC 文档内容ok
  4. （Codex）根据 SPEC 文档让 Codex 进行开发
  5. （Claude Code Plan 模式）参考 SPEC 文档 Review 代码，看是否存在遗漏的部分，以及提出优化建议
  6. （Claude Code）针对 Claude Code 给出的 Review 结果，给执行要求（补全哪些，优化哪些）
  7. （手动）由于微信小程序前端不太方便单元测试，需要手动跑和测试 feature
  8. （Codex / Claude Code）把实际体验发现的问题和修改要求丢给 AI 进一步调，有些问题 CC 搞不定就换给 Codex，通常总有一边能搞定，不行就两遍，实在不行就让 AI 指导自己对应问题的逻辑，自己搞懂/有猜想后指导 AI 修改。

其中 1, 2, 3, 4 步都可以在手机上完成，非常灵活方便。

写 SPEC 文档注意通常越复杂的需求，SPEC 也需要约详细，甚至需要拆分成多个子 SPEC

5.3.1.1 （例1）起始文档组

比如一开始的起始文档，可以拆成比如

  1. project-overview.spec.md：项目整体的说明文档，介绍项目，平台等等，以及索引其他进一步的文档。
  2. server-overview.spec.md：服务端整体的说明文档，架构（比如我用的 python + fastapi + sqlite）。
  3. serverdb-structure.spec.md：数据库结构说明文档，由于是订单管理小程序，数据结构本身比较重要。
  4. api.spec.md：API说明文档，约定并指导和规范前后端之后的开发。
  5. ui-design-guidelines.md：UI 规范文档，约定基本配色、按钮形状、基本布局、字号、偏好等等。
  6. client-overview.spec.md：客户端整体的说明文档，入口页面是哪个等等，并索引至各个页面的文档。
  7. page-xxx.spec.md：客户端各个页面的说明文档。

这样多个文档。把最核心的功能群一口气（在AI的协助下）规范并设计好，再让 AI 开发。

文档也可以分优先级，有些需要仔细看，有些大致看看，有些甚至可以不看，节约精力，比如：

  • T0 重点关注：对于这个小程序而言，数据比较关键。所以我仔细看和调了数据库结构说明文档。
  • T1 浏览即可：服务器架构、客户端页面文档就大致看看，没大问题就行。
  • T2 想看再看：其他的，比如具体页面文档就很多直接没看（虽然看看更好）
5.3.1.2 （例2）餐次图片 feature

一个 feature ,不算太复杂的话一般一个 spec 文档即可，比如 给图片管理和给餐次配图片的 SPEC 文档

以下为此次工程的部分文档（个人初期让AI写文档没太遵循 spec 规范，后面加 feature 才更注意 spec）

5.3.2 场景2：小需求或者改BUG

  1. （Codex / Claude Code）直接丢给 Codex / Claude Code 修改，不过最好大致看下修改的代码，避免改到不想改的部分
  2. （手动）实际再跑跑下看看有没有问题

处理 bug 或者优化，有的时候会遇到 Codex 重复修改几次没有成功的情况（比如想调整页面上两个元素到同一行，但多次要求，可能 claude 每次都自信满满说成功了，但实际客户端一看，还是歪的），这时可以丢给 Codex 再试试。

由于两者模型和 agent 实现不同，两者通常总有一方能搞定棘手问题。

当前很偶尔也会有双方都搞不定的情况。需要自己去研究一下问题（让 AI 指导着研究，一般也比较快）。

5.3.3 场景3：单元测试

  1. （手动）写测试需求，用例本身或者让 AI 想用例
  2. （Codex / Claude Code）扩展为测试需求文档
  3. （Codex / Claude Code）写单元测试代码
  4. （Claude Code）执行单元测试，遇到问题分析问题（可能测试代码/工程代码问题），修复并重新测。

不过由于是微信小程序，前端不太方便执行单元测试，我这次的测试都仅限于服务端。

5.3.3.1 （例1）复杂场景

一些复杂的场景用例，如

  1. A 登录，预期能正常登录
  2. A 注册，预期能注册成功且身份为普通用户
  3. B 登录，预期能正常登录且身份是管理员
  4. B 创建 T 餐次，可选项有鸡腿(限制1)，餐次总量限制 1 单，预期能创建成功
  5. A 下单 T 餐次，且选择鸡腿 *1，预期能下单成功且订单总价为 25，A 的待付款额度变为 25
  6. A 取消 T 餐次的订单，预期能取消成功，A 的待付款变为 0
  7. ….

跑下来一般能发现不少问题，且如果能顺利通过，可以极大增加自己对服务器逻辑的信心。

5.3.4 场景4：分析报告

有时遇到一些问题，或者想探究的东西，如

  1. 想检查当前的逻辑下数据库操作是否存在并发冲突的可能性
  2. 想实现一个功能，想了解一下有哪些实现途径，各自的特性/代价
  3. 慢慢检查前端是否存在废弃可以删除的页面
  4. 想了解当前某个逻辑是如何实现的，用到了哪些框架
  5. …

也可以让 AI 来分析，并且生成 md 报告放在工程某个目录下（如 doc/report）。

如果不急或者不在电脑前，可以用 codex 云端分析和写报告。

如果很急且在电脑前可以用 Claude Code（速度比较快）。

6. 打包

由于 dev 开发环境和 release 正式环境通常有区别，比如：

  • 开发用的服务器地址是 dev.pangruitao.com
  • 正式环境地址则可能是 pangruitao.com

且经常 dev 为了方便调试，部分页面也和正式版不同。比如

  • 我希望在 dev 模式下我可以自己设定 openid 方便我切换用户。但在正式版中则必须是拿用户code 去向微信请求，进而获得用户确定且唯一的 openid。
  • dev 模式下可能有很多正式版用不到的模块，比如单元测试等等，正式版没有最好。

但在有这些区别的情况下，又希望 dev 到 release 尽量地自动。

毕竟大部分的修改都是在 dev 上，总不会希望 dev 和 release 是两个工程，每次 dev 改完再用同样的方式改 release，这样又麻烦，且不安全（容易漏改）。

因此需要一个脚本能生成 release 版本的服务器和客户端。且这个过程一般也叫打包。

打包相关的脚本和相关的配置都可以让 AI 来生成。

之后则可以用 AI 生成好的打包脚本快速获得 release 版客户端服务器了

7. 正式部署

打包之后则是正式部署。

可以让 AI 给一个一键脚本，ssh 远程一键部署到正式服务器。

当然，也可以自己了解一下部署的具体过程（让AI指导即可），更有点掌控感，方便以后定位和处理问题。

8. 版本更新

版本更新是后期需要注意的一块。比如：

  1. 服务器升级：让 AI 指导升级流程，可能涉及：
    • 服务器 release 版代码工程更新
    • 数据库更新
    • env环境变量更新
    • 等等
  2. 客户端升级：
    • 微信开发者工具上传 release 的版本工程，即可体验体验版（仅项目成员可以体验）
    • 再在微信开放平台提交审核
    • 审核通过后可以发布为线上版

相对最大风险的是老版本兼容：

  1. 老版本客户端和新服务器的兼容
    • 提需求时尽量让新的修改能兼容老的 API
    • 不过实在不能兼容，问题也不大，就等客户端过审以后再更新服务器，同时微信平台上设置客户端强更。（但这样的话，通常额外需要一个预发布的测试环境，稍微麻烦一点）
  2. 老版本数据库和新服务器的兼容
    • 可以让 AI 准备数据库升级脚本。并且升级前做好备份。

9. 自动维护

可以设置一些必要的定时脚本，起到定期维护的工作（可以让 AI 写），比如：

  1. 定期备份数据库，并且定期删除时长超过比如 7 天的备份文件
  2. 定期清理临时文件（比如导出的供临时下载的 xlsx 表）

我暂时的习惯是每个这种自动脚本跑在一个 screen 下

10. 后记

10.1 踩过的坑

  1. 初期没有使用相对完善的 SPEC 文档，最后开发出来的内容很不可控。
  2. 用 duckdb ，长期报错，修好了过会又出问题。后来换成了更大众且模型更熟悉的 sqlite。
  3. 除非自己的知识能掌控复杂的结构，尽量用简单的结构和逻辑去实现 MVP 。
    • 不过 AI 经常为了实现一个功能想加很多复杂的框架支持，这时候需要尽量精简（也体现 SPEC 文档的价值）
  4. 能复用已经实现的 API 和原子操作就不要去增加新的操作。避免分支过多，自己跑测也不容易跑完。
    • 比如，修改订单 可以用 取消订单+新建订单 实现。
    • 比如，批量下单可以用 自动多次的 单个下单 实现。

10.2 最佳实践总结

  1. 用尽量大众的语言、框架、数据库。发挥 AI 实力。
  2. 用尽量自己了解的语言、框架、数据库。让自己更有把控能力。
  3. 先实现 SPEC 文档（AI 帮忙），并要 Review。
  4. 后期的修改要粗 Review 代码，特别关注 AI 有没有修改目标以外的逻辑和代码文件，可以增加自己对此次修改的信心，测试的时候可以放心地不去测不相关逻辑。
  5. Codex 负责搭框架、设计UI。Claude Code 负责快速解决 bug。
  6. 术语尽量精确，可以了解下技术原理，让自己能更精准描述需求并指导AI。
  7. 多用 plan mode 或者让 AI 写文档（算是个进一步的 plan mode），通过和 AI 互动设计，厘清思路再执行。
  8. 描述问题时可以把自己当成执行者。可以尽量清晰描述，毕竟自然语言模糊区间很多。
    • 比如参考 QA 的 JIRA：”在 XX 页面的YY地方。目前有ZZ表现。预期是FF表现。可以参考AA页面WW地方的正确实现。“
  9. 把 SPEC 文档经由AI到工程代码的过程，视作代码经由编译器解释器实际执行的过程。
    • 正如曾经，写好一次代码可以重复执行很多遍，遇到问题就微调代码
    • 如今写好一次 SPEC 文档库，也可以每当遇到太大问题就删掉所有代码，修改文档，重新生成整个代码工程（虽然有 token 成本）
    • 即把 SPEC 文档当作元编程，即更上层但同时更好管理和阅读的代码，认真管理。

最后，保持学习，保持进步，知识越深越广，更可能把 AI 掌控和运用得更好。

相关文章

  1. AI开发的一些思考体会
  2. QT3 用Backtrader实现AH溢价交易策略
  3. Debian下用docker快速搭建wordpress
  4. 双子主题打油诗
  5. 泊松分布推导
  6. Docker安装教程
  7. python飞书机器人拉群聊历史消息

发表评论