#moon-miniprogram（兔小程序）

用 MoonBit 写微信小程序：业务逻辑全部是纯 MoonBit——类型安全、可单测、 可属性测试；编译产物是一个 CommonJS 模块，页面 JS 只剩一行装配代码。

#目录

• 为什么有它
• 特性
• 30 秒上手
• 概念速览
• 性能
• 测试
• 使用文档
• 仓库结构
• 路线图
• 参与

#为什么有它

#特性

• ⚡ 状态自动 diff —— set_state 按 React setState 语义合并，diff 引擎自动展开到 最小 setData 路径补丁；数据没变化时连 setData 都不调（实测单次更新传输量缩小 最多 ~713 倍）
• 🔀 跨页 store —— 一个 create_store + 页面 bind_store，任意页面一处更新， 所有订阅页面自动收到最小补丁（对标 React context / mobx）
• 🧭 声明式路由 —— register_route 白名单参数，导航不手拼 url；拼错参数自动 剥离并 console.warn，绝不 raise
• 🧩 页面 / 组件 / App 完整模型 —— properties 类型名自动翻译成微信构造函数、 observers、pageLifetimes、带返回值的钩子（onShareAppMessage）、全局数据
• 🧪 可复用无头测试基建 —— sim/wx-sim.js 在 node 里模拟微信运行时 （含路径感知 setData），任何用本框架的项目都能不装微信工具先测起来
• 🔧 一键 CLI + 脚手架 —— node scripts/new.cjs 生成项目，node mmp.cjscheck/test/build/dev/release 一条龙

#30 秒上手

# 1. 开新项目（会自动从 mooncakes 拉取本框架）
node scripts/new.cjs myapp && cd myapp

# 2. 单测 / 构建并装配到小程序壳
node mmp.cjs test
node mmp.cjs dev        # watch 模式：.mbt 一变就自动重编译

# 3. 微信开发者工具（测试号即可）打开 myapp/miniprogram/，点按钮看界面

let counter_page : @mp.PageDef = {
  path: "pages/index/index",
  data: @mp.jobj([("count", @mp.jnum(0.0))]),
  handlers: [
    (
      "onTap",  // 名字即微信事件/方法名，WXML bind:tap="onTap" 直接命中
      (ctx, _payload) => {
        let n = match ctx.get_data() {
          Some(Json::Object(m)) =>
            match m.get("count") {
              Some(Json::Number(d, ..)) => d + 1.0
              _ => 1.0
            }
          _ => 1.0
        }
        // set_state：自动 diff，实际 setData 只含 count 的变化路径
        ctx.set_state(@mp.jobj([("count", @mp.jnum(n))]))
      },
    ),
  ],
  returns: [],  // 需要向微信返回对象的钩子（onShareAppMessage 等）放这里
}

// app.js            require("./engine/moon-engine.js").launch();
// pages/index/index.js  require("../../engine/moon-engine.js").page("pages/index/index");

#概念速览

#性能

#测试

moon test                              # 37 个单测（含 200 轮随机不变式）
powershell scripts/build-example.ps1   # 构建 + 38 项端到端冒烟（node 模拟微信运行时）

#使用文档

1. 从零到真机：脚手架 → CLI → 微信开发者工具全流程
2. 页面与事件 / 状态管理 / 跨页 store / 自定义组件
3. 路由与导航 / wx API 参考
4. 📊 wx API 覆盖对照表（微信官方 ↔ 本框架，约 55 个 pub 函数）
5. 无头测试 / 构建与发布
6. 常见坑与 FAQ

#仓库结构

runtime/          框架核心：Page/App/Component 模型、diff 引擎、store、router、
                  wx 绑定 + 扩展绑定、平台探测（platform.mbt）
engine/           最小示例 fixture（counter + about + tag，冒烟宿主，无业务）
engine-export/    CJS 导出包装（foreign_library）
scripts/          new.cjs 脚手架 · mmp.cjs 一键 CLI · sim/wx-sim.js 模拟器 · smoke.js · minify.cjs
docs/             使用指南 · 参赛说明 · rfc/（平台适配设计）
moon.mod          包定义（mooncakes 发布入口）

#路线图

• Page/App/Component 模型 + wx 类型绑定 + set_state 自动 diff（含随机不变式）
• 带回值钩子、pageLifetimes、全局数据、可复用无头模拟器
• 跨页状态订阅 store（v0.3.1）
• 声明式路由 + 参数白名单（v0.3.2）
• 一键 CLI + 脚手架（v0.3.3）
• 错误边界钩子 + 重复注册警告 + wx API 覆盖补全（v0.3.4）
• 文档体系化（v0.3.5）

• 平台适配实现（支付宝/抖音——设计已完成：RFC 0001 + 平台探测）
• 分包 / 独立分包支持
• 类型化 storage key + 路由参数反序列化助手
• 组件/UI 物料包（组件生态：定义四件套见使用指南）

#参与

git clone https://github.com/Magic486/moon-miniprogram
cd moon-miniprogram
moon test                                # 33 单测
powershell scripts/build-example.ps1     # 36 冒烟
node scripts/new.cjs demo && cd demo     # 体验脚手架 + mmp

• 反馈 / 讨论：GitHub Issues
• 包：mooncakes.io Magic486/moon-miniprogram
• 里程碑：GitHub Releases

#License