---

快速开始

Lovrabet SDK 是一个轻量级的 JavaScript/TypeScript SDK，让您能够快速接入 Lovrabet 平台的数据服务。

💡 推荐方式使用 Lovrabet CLI 可以一键生成配置，省去手动配置的麻烦。请参考 CLI 5 分钟快速上手。

安装

使用 npm 或 yarn 安装 SDK：

npm install @lovrabet/sdk
# 或
yarn add @lovrabet/sdk

⚡ 5 分钟上手

1. CLI 自动配置（推荐）

使用 CLI 一键生成配置，然后直接使用：

import { createClient } from "@lovrabet/sdk";
import "./api/api"; // 导入 CLI 生成的配置

const client = createClient();

// 标准方式访问（推荐）- 使用 dataset_ 前缀 + datasetCode
const users = await client.models.dataset_71494bcba13f4ec7858abe90794183ad.filter({
  currentPage: 1,
  pageSize: 20,
});

// 别名方式访问（语法糖）- 使用配置的 alias
const users = await client.models.users.filter({
  currentPage: 1,
  pageSize: 20,
});

💡 标准方式 vs 别名方式：两者功能完全一致。标准方式使用 datasetCode，全局唯一，AI 友好；别名方式更易读，是语法糖。

2. 手动配置方式

import { registerModels, createClient } from "@lovrabet/sdk";

// 注册配置
registerModels({
  appCode: "your-app-code",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "users",
      alias: "users",      // 可选：模型别名
      name: "用户表",      // 可选：UI 显示名称
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "posts",
      alias: "posts",
    },
  ],
});

const client = createClient();

// 标准方式访问（推荐）
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();
// 别名方式访问（语法糖）
const users = await client.models.users.filter();

📊 响应数据结构

列表查询响应

const response = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

console.log(response.tableData); // 数据列表
console.log(response.total); // 总数
console.log(response.currentPage); // 当前页
console.log(response.pageSize); // 页大小

单条记录响应

const user = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.getOne("user-id");
console.log(user); // 用户详情对象

🎯 CLI 自动生成配置

如果您使用 Lovrabet CLI 工具，配置文件会自动生成：

src/api/api.ts (CLI 自动生成)

import { registerModels, type ModelsConfig } from "@lovrabet/sdk";

export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
  appCode: "app-c4c89304",
  models: [
    {
      datasetCode: "71494bcba13f4ec7858abe90794183ad",
      tableName: "users",
      alias: "users",
      name: "用户管理",
    },
    {
      datasetCode: "d26ed512e878461ca97d287a47606fd3",
      tableName: "posts",
      alias: "posts",
      name: "文章管理",
    },
  ],
} as const;

// 自动注册默认配置
registerModels(LOVRABET_MODELS_CONFIG);

src/api/client.ts (业务代码)

import { createClient } from "@lovrabet/sdk";
import "./api"; // 导入配置文件，执行注册

// 创建客户端实例
export const lovrabetClient = createClient();

// 在组件中使用
// import { lovrabetClient } from '@/api/client';
// 标准方式：lovrabetClient.models.dataset_71494bcba13f4ec7858abe90794183ad.filter()
// 别名方式：lovrabetClient.models.users.filter()

🛠️ 基础 CRUD 操作

// 查询列表（带分页和条件过滤）
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter({
  where: { status: { $eq: "active" } },
  currentPage: 1,
  pageSize: 10,
});

// 获取单条记录
const user = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.getOne("user-id");

// 创建新记录
const newUser = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.create({
  name: "Jane Doe",
  email: "jane@example.com",
  status: "active",
});

// 更新记录
const updatedUser = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.update("user-id", {
  name: "Jane Smith",
  email: "jane.smith@example.com",
});

// 删除记录
await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.delete("user-id");

💡 以上示例使用标准方式 dataset_xxx，也可以使用别名方式 client.models.users.xxx()。

🆕 v1.2.0 新特性

模型访问方式

v1.2.0 支持标准方式和别名方式访问模型：

// 标准方式（推荐）- 使用 dataset_ 前缀 + datasetCode
// 全局唯一，便于 AI 工具生成代码
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

// 别名方式（语法糖）- 使用配置的 alias
// 方便人类阅读，功能与标准方式完全一致
const users = await client.models.users.filter();

💡 别名只是一个指向，内部仍使用 datasetCode 访问，所有特性与标准方式完全相同。

模型管理器增强

// 获取所有模型详细信息
const details = client.getModelListDetails();
// 返回: [{ datasetCode: '8d2dcbae08b54bdd84c00be558ed48df', alias: 'users', name: '用户表' }, ...]

// 动态添加模型
client.addModel({
  datasetCode: 'f7e6d5c4b3a2901234567890fedcba98',
  tableName: 'products',
  alias: 'products'
});

📖 下一步

恭喜！您已经掌握了 Lovrabet SDK 的基础用法。接下来可以深入学习：

• 📋 配置详解 - 了解各种配置方式
• 🔐 认证配置 - 配置用户认证
• 📊 API 使用指南 - 深入了解 API 操作
• 🎯 TypeScript 支持 - 类型安全的开发体验

❓ 遇到问题？

如果在使用过程中遇到问题，可以查看：

• 🛠️ 故障排查 - 常见问题解答
• 📞 技术支持 - 联系 Lovrabet 技术团队