跳到主要内容

Rabetbase 常见问题（FAQ）

本页汇总 Rabetbase 开发体系（CLI + SDK + Skill + BaaS）的常见问题。如果你的问题不在此列，可以在 Lovrabet 社区提问。

一、基础概念​

Q1: Rabetbase 和 Lovrabet 是什么关系？​

Lovrabet 面向所有的业务人员和开发人员，是一套完整的AI-Native 业务系统的生成平台。

Rabetbase 是 Lovrabet 的开发者基础设施层。它向上层应用提供标准化的数据访问、权限控制和 API 能力；向开发者提供 CLI、SDK、Skill 三件套——在终端完成从数据操作到项目部署的全流程，无需自建后端。

Lovrabet 平台

  • AI-Native 业务系统生成
  • DB Agent / Vibe Coding / 需求描述生成系统
  • 工作台 / 权限管理
  • 运行环境托管

Rabetbase 开发体系——隶属于Lovrabet平台

  • CLI：终端操作工具
  • SDK：数据访问接口
  • Skill：AI 辅助开发
  • BaaS：后端即服务

图片资源待同步：ZkiZbkU5so0ZVxxtPcYcB628nz5

Q2: 没有后端开发经验，能用 Rabetbase 吗？​

可以。Rabetbase 的 BaaS 层已经把后端能力（数据库、API、权限、认证）全部封装好了。你只需要：

  1. 用 Lovrabet 平台创建应用和数据表
  2. 用 rabetbase api pull 生成 SDK 配置
  3. 用 SDK 的 filter、create、update、delete 操作数据

整个过程不需要写后端代码、不需要部署服务器。

Q3: Rabetbase CLI 2.0 和旧版 lovrabet CLI 有什么区别？​

维度旧版（lovrabet）新版（rabetbase 2.0）
命令前缀lovrabetrabetbase
构建部署lovrabet buildrabetbase run build
AI 集成MCP ServerSkill（社区标准）
命令体系功能分散统一 service + command 两级结构

如果你还在用旧版 lovrabet CLI，请升级到 rabetbase 2.0。旧版已停止维护。

二、安装与配置​

Q4: 如何安装 Rabetbase CLI？​

安装后验证：

rabetbase --version
rabetbase --help

Q5: Skill 如何安装？​

Skill 是 AI 辅助开发的规则集，让 Claude Code、Cursor 等工具能正确使用 Rabetbase CLI：

npx skills add lovrabet/rabetbase --global

安装后，在 Claude Code 中 AI 会自动获取你的数据集结构，生成的代码基本一次通过。

Q6: 认证方式有哪些？​

Rabetbase 支持两种认证模式：

模式认证方式适用场景
WebAPICookie（浏览器登录）前端应用
OpenAPIAccessKey + SecretKey后端服务、CLI

前端推荐使用 Cookie 认证（用户在浏览器中登录后自动获取），后端和 CLI 使用 AccessKey 认证。

AccessKey 不要硬编码在源码中！使用环境变量。

三、CLI 常用命令​

Q7: 如何创建新项目？​

rabetbase project create my-app
cd my-app
rabetbase api pull --appcode your-app-code

project create 会生成完整的项目脚手架（含构建配置、路由、API 客户端）。api pull 会根据你的应用数据生成 SDK 类型定义。

Q8: 如何同步菜单到主应用？​

rabetbase menu sync

CLI 会自动扫描 src/pages 下的页面，智能提取菜单名称，批量创建菜单。

Q9: 如何构建和部署？​

rabetbase run build

构建产物在 dist/ 目录，可以直接部署到 CDN。

Q10: 常用 CLI 命令速查​

命令说明
rabetbase project create创建项目
rabetbase api pull拉取 API 配置
rabetbase dataset detail查看数据集结构
rabetbase sql validate校验 SQL 语法
rabetbase sql save保存自定义 SQL
rabetbase sql exec执行自定义 SQL
rabetbase bff new创建 Backend Function
rabetbase bff push推送 BFF 到平台
rabetbase menu sync同步菜单
rabetbase run build构建项目
rabetbase auth login登录认证
rabetbase app list查看应用列表

四、SDK 数据操作​

Q11: SDK 客户端怎么初始化？​

推荐使用单例模式，整个应用共享一个客户端实例：

// src/api/client.ts
import { createClient } from "@lovrabet/sdk";

export const client = createClient({
  appCode: "your-app-code",
});

不要在每个组件中重复创建客户端。

Q12: filter、getOne、create、update、delete 怎么用？​

import { client } from "@/api/client";

// 查询列表（分页）
const { tableData, total } = await client.models.customers.filter({
  currentPage: 1,
  pageSize: 20,
});

// 查询单条
const customer = await client.models.customers.getOne("123");

// 创建
const newId = await client.models.customers.create({
  name: "张三",
  phone: "13800138000",
});

// 更新
await client.models.customers.update("123", { name: "李四" });

// 删除（仅 WebAPI 模式）
await client.models.customers.delete("123");

Q13: 删除操作报错怎么办？​

delete 操作只在 WebAPI 模式（Cookie 认证）下可用。如果你用的是 OpenAPI 模式，用"软删除"：

await client.models.customers.update(id, {
  status: "deleted",
  deleted_at: new Date().toISOString(),
});

五、SQL 与 Backend Function​

Q14: 什么时候用自定义 SQL？​

场景推荐
单表增删改查SDK 的 filter/create/update/delete
单表条件查询filter + 搜索/筛选参数
跨表关联查询自定义 SQL
复杂聚合统计自定义 SQL
数据分组求和自定义 SQL

Q15: 自定义 SQL 怎么写？​

创建 .rabetbase/sql/ 目录下的 SQL 文件：

-- @lovrabet sqlName=myQuery description=我的查询
SELECT
  category,
  COUNT(*) as count,
  SUM(amount) as total
FROM dataset_orders
WHERE 1=1
  
    AND create_time >= #{startDate}
  
GROUP BY category

关键语法：

  • #{paramName} — 参数化查询（防 SQL 注入）
  • 条件片段建议按参数显式拼接，避免裸字符串注入

Q16: 事务里怎么写多表操作？​

await context.client.models.transaction(async ({ models }) => {
  // 创建主表
  const orderId = await models[TABLES.orders].create(orderData);

  // 创建明细
  for (const item of items) {
    await models[TABLES.orderItems].create({ orderId, ...item });
  }
});

关键规则：

  • 使用 context.client.models 而非 tx.models
  • 异常自动回滚
  • 不要在事务中执行耗时操作

六、AI 辅助开发​

Q18: Skill 能帮我做什么？​

Skill 让 AI 工具（Claude Code、Cursor）理解你的业务数据结构，生成的代码一次通过：

  • 自动获取数据集结构（表名、字段名、字段类型）
  • 正确使用 CLI 命令（不会猜字段名）
  • 遵循最佳实践（单例模式、错误处理、分页）
  • 自动执行 CLI 命令（创建项目、拉取 API、推送 BFF）

Q19: 如何用 AI 辅助开发一个完整功能？​

在 Claude Code 中描述需求即可：

用 rabetbase CLI 帮我创建一个客户管理页面，包含客户列表（支持搜索和分页）、客户详情页（支持编辑）、新建客户表单（有手机号校验）。

AI 会自动完成：

  1. rabetbase project create 创建项目
  2. rabetbase api pull 生成 SDK
  3. 生成所有页面代码
  4. rabetbase run build 构建
  5. rabetbase menu sync 同步菜单

Q20: 为什么 AI 生成的代码不正确？​

可能的原因：

  1. Skill 未安装 — 运行 npx skills add lovrabet/rabetbase --global
  2. API 未拉取 — 运行 rabetbase api pull 更新 SDK 配置
  3. 描述不够具体 — 明确指定数据集名称、字段名、页面结构

七、性能与安全​

Q21: 列表查询怎么优化？​

  1. 加分页 — 始终传 currentPage 和 pageSize
  2. 搜索加防抖 — 300ms debounce
  3. 只查需要的字段 — SQL 避免 SELECT*
  4. 加 LIMIT — SQL 查询限制返回行数

Q22: AccessKey 泄露了怎么办？​

  1. 在 Lovrabet 平台重新生成 AccessKey
  2. 更新环境变量
  3. 检查是否有硬编码的旧 Key

永远不要在前端代码中硬编码 AccessKey。前端使用 Cookie 认证或 Token 认证。

Q23: 敏感数据怎么处理？​

前端脱敏：

const maskPhone = (phone: string) => {
  return phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
};
// 138****8000

后端脱敏（推荐）：使用 Backend Function 的后验函数，在数据返回前统一处理。

八、故障排查​

Q24: CLI 命令报错 "command not found"？​

确认安装路径：

which rabetbase
rabetbase --version

如果找不到，重新安装或检查 PATH 配置。

Q25: API 调用返回 401？​

检查认证状态：

rabetbase auth login

如果是 AccessKey 认证，确认环境变量已设置：

echo $LOVRABET_ACCESS_KEY

Q26: BFF 推送失败？​

常见原因：

  1. 语法错误 — 先用 rabetbase bff status 检查
  2. 数据集编码不对 — 检查 TABLES 常量中的编码
  3. 网络问题 — 检查网络连接

Q27: SQL 执行 execSuccess 为 false？​

常见原因：

  1. SQL 语法错误（检查 XML 转义）
  2. 表或字段名不正确
  3. 参数类型不匹配

调试方法：

rabetbase sql exec --sqlcode  --params '{}' --format json

更多问题？查看以下资源：集成开发指南、SDK 使用指南、CLI 使用指南，均可通过 open.lovrabet.com 获取。