教程导读与项目创建

这个教程适合谁？

• 你是刚接触 Lovrabet 体系的新手
• 你想做个性化开发，但不知道从哪开始
• 你希望有一个手把手的完整案例

学完能得到什么？

• 掌握完整的开发流程：从创建项目到上线
• 能独立开发一个客户管理模块（列表、详情、表单、报表）
• 理解各个工具（CLI、SDK、MCP、SQL）怎么配合使用

预计学习时间：60-90 分钟（可以分段学习）

---

我们要做什么？

我们要从零开始，开发一个客户管理系统，包含以下功能：

功能	说明	你会学到
客户列表	展示客户数据，支持筛选和分页	SDK 基础查询
客户详情	点击查看客户详细信息	数据关联查询
新增客户	表单填写，保存到数据库	数据创建
编辑客户	修改已有客户信息	数据更新
销售报表	统计客户销售数据	自定义 SQL
数据校验	保存前检查数据是否合法	Backend Function

最终效果：一个完整的业务模块，可以直接投入使用。

---

学习路径

📦 第一阶段：准备工作（10分钟）
   └── [1. 环境准备与项目创建](#1-环境准备与项目创建)

📦 第二阶段：基础功能（30分钟）
   ├── [2. 列表页：分页查询与筛选](./scenario-data-list)
   ├── [3. 详情页：查看与编辑数据](./scenario-data-detail)
   └── [4. 表单页：新增与修改数据](./scenario-data-form)

📦 第三阶段：进阶功能（30分钟）
   ├── [5. 主从表：订单与订单明细的事务处理](./scenario-master-detail)
   ├── [6. 关联查询：订单显示客户信息](./scenario-multi-table)
   └── [7. 报表页：SQL 实现销售统计](./scenario-data-report)

📦 第四阶段：高级功能（20分钟）
   ├── [8. 数据校验：后端拦截非法数据](./scenario-bf-pre-validation)
   ├── [9. 数据脱敏：手机号、身份证处理](./scenario-bf-post-validation)
   └── [10. 复杂统计：BF 中调用 SQL](./scenario-bf-sql)

📦 第五阶段：上线部署（10分钟）
   └── [11. 构建与部署](#11-构建与部署)

---

1. 环境准备与项目创建

1.1 你需要准备什么？

在开始之前，请确保你已经：

准备项	要求	如何获取
Node.js	版本 >= 18	官网下载
代码编辑器	VS Code 推荐	官网下载
Lovrabet 账号	已注册	注册地址
应用 AppCode	已创建应用	在工作台创建应用后获取

什么是 AppCode？

AppCode 是你的应用在 Lovrabet 平台上的唯一标识。在 Lovrabet 工作台 → 应用设置 → 基本信息 中可以找到，格式类似 app-c4c89304。

1.2 安装 CLI 工具

CLI（命令行工具）能帮你快速创建项目、生成代码、部署上线。

打开终端（Windows 用户用 PowerShell 或 Git Bash），执行：

# 安装 CLI
npm install -g @lovrabet/cli

# 验证安装成功
lovrabet --version

看到版本号就说明安装成功了。

1.3 登录你的账号

lovrabet auth

执行后会自动打开浏览器，登录你的 Lovrabet 账号。登录成功后，终端会显示：

✔ 登录成功！凭证已保存到本地

以后执行 CLI 命令时，会自动使用这个登录状态。

1.4 创建项目

# 创建项目
lovrabet create

CLI 会问你几个问题：

* 项目名: customer-management
* 应用 AppCode [可选]: app-c4c89304  ← 填你的 AppCode
* 是否要自动拉取 API 配置？ ▶ Yes   ← 选 Yes

✔ 复制项目文件
✔ 更新项目配置
✔ 安装 npm 依赖
✔ 拉取 API 配置

🎉 项目创建成功！

  cd customer-management
  lovrabet start

拉取 API 配置做了什么？

CLI 会自动从平台获取你应用的所有数据集信息，生成 SDK 调用代码。这样你在写代码时，IDE 能自动提示字段名和类型。

1.5 启动开发服务器

cd customer-management
lovrabet start

浏览器会自动打开 http://localhost:5173，你能看到项目的初始页面。

1.6 配置 AI 辅助（强烈推荐）

如果你用 Cursor 或 Claude Desktop，配置 MCP 能让 AI 理解你的业务数据，生成的代码更准确。

在项目根目录创建 .cursor/mcp.json（Cursor）或编辑 Claude Desktop 配置：

{
  "mcpServers": {
    "lovrabet-dataset": {
      "command": "npx",
      "args": ["-y", "@lovrabet/dataset-mcp-server"],
      "env": {
        "LOVRABET_APP_CODE": "app-c4c89304"
      }
    }
  }
}

配置 MCP 的好处

• AI 能自动获取你的数据表结构
• 生成的代码字段名 100% 准确
• 复杂查询（JOIN、聚合）让 AI 帮你写
• 开发效率提升 3-5 倍

---

第一阶段完成！

现在你已经：

• ✅ 安装了 CLI 工具
• ✅ 创建了项目
• ✅ 启动了开发服务器
• ✅ 配置了 AI 辅助（可选）

下一步：开始开发客户列表页，这是最基础的功能，也是你熟悉开发流程的起点。

---

11. 构建与部署

当你完成了所有功能开发，就可以构建并部署到生产环境了。

11.1 构建项目

lovrabet build

构建完成后，dist/ 目录会生成两个文件：

dist/
├── index.js      # JavaScript 代码
└── index.css     # 样式文件

11.2 上传到 CDN

把这两个文件上传到你的 CDN 或服务器，获取 HTTPS 访问地址：

• https://cdn.example.com/customer-management/index.js
• https://cdn.example.com/customer-management/index.css

没有 CDN 怎么办？

可以用阿里云 OSS、腾讯云 COS、自己的服务器（需配置 HTTPS），或者 Vercel、Netlify 等免费托管服务。

11.3 设置菜单名称（重要）

在同步菜单之前，确保你的页面有正确的中文名称。CLI 会按以下优先级提取菜单名称：

displayName > 组件名 > 文件路径

推荐方式：使用 displayName

function CustomerList() {
  // ...
}

// 设置菜单显示名称
CustomerList.displayName = "客户列表";

export default CustomerList;

箭头函数写法：

const CustomerList = () => {
  // ...
};

CustomerList.displayName = "客户列表";
export default CustomerList;

方式	示例	菜单名称
displayName（推荐）	Component.displayName = "客户列表"	客户列表
组件名	function CustomerList()	CustomerList
文件路径	src/pages/customer/list.tsx	customer/list

11.4 同步菜单到工作台

首次部署时，使用 sync 命令创建菜单：

lovrabet menu sync

CLI 会扫描你本地的页面，让你选择要同步的菜单：

  菜单名称        本地  线上
  客户列表        ✓     ✗     (需要创建)
  客户详情        ✓     ✗     (需要创建)
  销售报表        ✓     ✗     (需要创建)

* 请选择要同步的菜单:
  [✓] 客户列表
  [✓] 客户详情
  [✓] 销售报表

* JS 链接: https://cdn.example.com/customer-management/index.js
* CSS 链接: https://cdn.example.com/customer-management/index.css

√ 菜单创建完成

现在打开 Lovrabet 工作台，就能在菜单里看到你开发的页面了！

11.5 后续迭代更新

修改代码后重新部署，使用 update 命令批量更新资源链接：

# 1. 重新构建
lovrabet build

# 2. 上传到 CDN（得到新的链接）
# https://cdn.example.com/customer-management/index-v2.js
# https://cdn.example.com/customer-management/index-v2.css

# 3. 批量更新所有菜单的资源链接
lovrabet menu update

sync vs update 对比

命令	用途	使用场景
menu sync	创建新菜单	首次部署、新增页面
menu update	更新资源链接	修改代码后重新部署

详细文档

• 主子应用架构 — 理解 Lovrabet 的微前端架构
• 同步菜单到工作台 — sync/update 命令完整说明
• SDK 配置 — 生产环境配置

---

恭喜你！

你已经完成了从零到一的完整学习，掌握了：

技能	说明
CLI 使用	创建项目、构建、部署、菜单同步
SDK 查询	filter、getOne、create、update
自定义 SQL	复杂报表、统计分析
Backend Function	数据校验、业务逻辑
AI 辅助开发	配置 MCP，让 AI 理解业务

---

接下来可以学什么？

深入学习

• SDK 入门 — SDK 完整介绍
• Filter API — 高级查询技巧
• SQL API — 自定义 SQL 详解
• Backend Function — 后端业务逻辑扩展
• 错误处理 — 异常捕获和处理

架构与部署

• 主子应用架构 — 微前端集成详解
• 同步菜单到工作台 — 部署流程完整说明
• CLI 命令参考 — 所有 CLI 命令

其他资源

• 最佳实践 — 开发规范和性能优化建议
• 常见问题 — 遇到问题先看这里
• OpenAPI 文档 — 小程序、App 直接调接口
• MCP 配置 — AI 辅助开发进阶