配置详解

本文档帮助你理解 Lovrabet SDK 的配置机制，让你能够快速上手并高效使用。

为什么需要配置？

在使用 Lovrabet SDK 访问数据时，每个数据集都有一个唯一的 datasetCode（如 8d2dcbae08b54bdd84c00be558ed48df）。如果没有配置机制，你的代码会变成这样：

TypeScript

// ❌ 没有配置：每次调用都要手动填写 appCode 和 datasetCode
const response = await fetch('/api/data', {
  body: JSON.stringify({
    appCode: 'my-app',
    datasetCode: '8d2dcbae08b54bdd84c00be558ed48df',
    // ...其他参数
  })
});

配置机制解决了这些痛点：

✅ 一次配置，到处使用 - 不用每次都填写 appCode 和 datasetCode
✅ 代码更简洁 - client.models.dataset_xxx.filter() 一行搞定
✅ 类型安全 - TypeScript 智能提示，减少出错
✅ AI 友好 - datasetCode 全局唯一，便于 AI 工具生成准确代码

快速开始：CLI 自动配置（推荐）

最省心的方式：使用 Lovrabet CLI 一键生成配置文件。

**💡 还没安装 CLI？**请先按照 CLI 安装指南完成安装，然后按照 5 分钟快速上手创建项目。

第 1 步：拉取配置

在项目根目录执行：

Bash

lovrabet api pull

📖 详细参数说明请参考 CLI API 集成文档

CLI 会自动从平台拉取你的数据集信息，生成配置文件 src/api/api.ts：

TypeScript

// 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: "orders",
      alias: "orders",
      name: "订单管理",
    },
  ],
} as const;

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

第 2 步：使用配置

在业务代码中直接创建客户端并使用：

TypeScript

import { createClient } from "@lovrabet/sdk";
import "./api/api"; // 引入配置文件，自动注册

const client = createClient();

// 标准方式访问（推荐）- 使用 dataset_ 前缀 + datasetCode
const users = await client.models.dataset_71494bcba13f4ec7858abe90794183ad.filter();
const orders = await client.models.dataset_d26ed512e878461ca97d287a47606fd3.getOne("order-001");

💡 为什么推荐标准方式？ datasetCode 全局唯一，AI 工具（如 Claude、Cursor）生成代码时不会产生歧义。

第 3 步（可选）：使用别名

如果你觉得 datasetCode 太长不方便阅读，可以使用配置中的 alias 别名：

TypeScript

// 别名方式（语法糖）- 使用配置的 alias
const users = await client.models.users.filter();
const orders = await client.models.orders.getOne("order-001");

📌 注意：别名只是一个指向，内部仍使用 datasetCode 访问，所有特性与标准方式完全一致。

手动配置（适用于特殊场景）

如果你不使用 CLI，或者需要更灵活的控制，可以手动配置。

💡 推荐方式：大多数情况下建议使用 CLI 自动配置，省时省力。

方式 1：预注册配置

使用 registerModels() 预先注册配置，然后在任意位置创建客户端：

TypeScript

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

// 注册配置（通常在应用入口执行一次）
registerModels({
  appCode: "my-app",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "users",
      alias: "users",  // 可选
      name: "用户表",  // 可选
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "orders",
      alias: "orders",
      name: "订单表",
    },
  ],
});

// 在任意位置创建客户端（无需再传配置）
const client = createClient();

// 标准方式访问
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

适用场景：

需要在多个模块中共享同一配置
希望配置与业务逻辑分离

方式 2：直接传入配置

创建客户端时直接传入配置对象：

TypeScript

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

const client = createClient({
  appCode: "my-app",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "users",
      alias: "users",
    },
  ],
});

// 标准方式访问
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

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

适用场景：

临时测试或一次性使用
需要完全控制每个客户端的配置

模型访问方式详解

SDK 提供两种访问模型的方式，功能完全一致：

标准方式（推荐）

使用 dataset_ 前缀 + datasetCode 访问：

TypeScript

// 格式：client.models.dataset_[datasetCode]
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();
const order = await client.models.dataset_a1b2c3d4e5f6789012345678abcdef12.getOne("id");

为什么是标准方式？

✅ 全局唯一 - datasetCode 是数据集的唯一标识，永不冲突
✅ AI 友好 - AI 工具生成代码时能精确定位，减少幻觉
✅ 无需配置 - 即使没有预先配置模型，也可直接访问

别名方式（语法糖）

如果在配置中定义了 alias，可以用更短的名称访问：

TypeScript

// 格式：client.models.[alias]
const users = await client.models.users.filter();
const order = await client.models.orders.getOne("id");

关于别名：

📌 只是语法糖 - alias 只是一个指向，内部仍使用 datasetCode
📌 功能完全一致 - 所有 API 方法、类型提示都与标准方式相同
📌 提升可读性 - 方便人类开发者快速阅读代码

对比总结

方式	格式	特点
标准方式	`client.models.dataset_[datasetCode]`	全局唯一，AI 友好，推荐
别名方式	`client.models.[alias]`	语法糖，人类友好，需配置 alias

进阶配置

多项目配置管理

如果你同时开发多个项目，可以注册多个配置并按名称切换：

TypeScript

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

// 注册多个项目配置
registerModels(CONFIG_A, "project-a");
registerModels(CONFIG_B, "project-b");

// 按名称创建不同项目的客户端
const clientA = createClient("project-a");
const clientB = createClient("project-b");

ClientConfig 扩展选项

创建客户端时可以传入额外配置：

TypeScript

const client = createClient({
  apiConfigName: "default",     // 使用哪个预注册配置
  token: "your-auth-token",     // 用户认证 Token
  accessKey: "your-access-key", // OpenAPI 访问密钥
  secretKey: "your-secret-key", // OpenAPI 密钥
  serverUrl: "https://custom.api.com", // 自定义服务器地址
  options: {
    timeout: 30000,             // 请求超时时间（毫秒）
    onError: (error) => {       // 错误回调
      console.error("API Error:", error);
    },
    onRedirectToLogin: () => {  // 登录过期回调
      window.location.href = "/login";
    },
  },
});

动态添加模型

运行时动态添加新模型：

TypeScript

// 动态添加模型
client.addModel({
  datasetCode: "f7e6d5c4b3a2901234567890fedcba98",
  tableName: "products",
  alias: "products",
  name: "产品管理",
});

// 立即可用
const products = await client.models.dataset_f7e6d5c4b3a2901234567890fedcba98.filter();
// 或使用别名
const products = await client.models.products.filter();

获取模型信息

TypeScript

// 获取所有已配置的模型详情
const details = client.getModelListDetails();
// 返回: [{ datasetCode: '...', alias: 'users', name: '用户表' }, ...]

// 获取所有已注册的配置名称
import { getRegisteredConfigNames } from "@lovrabet/sdk";
console.log(getRegisteredConfigNames()); // ['default', 'project-a', 'project-b']

配置结构参考

ModelsConfig

TypeScript

interface ModelsConfig {
  appCode: string;           // 应用代码
  models: Array<{
    datasetCode: string;     // 数据集代码（必填，唯一标识）
    tableName: string;       // 数据表名（必填）
    alias?: string;          // 模型别名（可选，用于 client.models.alias 访问）
    name?: string;           // 显示名称（可选，用于 UI 展示）
  }>;
}

ClientConfig

TypeScript

interface ClientConfig {
  apiConfigName?: string;    // 预注册配置名称
  serverUrl?: string;        // 自定义服务器地址
  token?: string;            // 用户认证 Token
  accessKey?: string;        // OpenAPI 访问密钥
  secretKey?: string;        // OpenAPI 密钥
  options?: {
    timeout?: number;        // 请求超时时间（毫秒）
    onError?: (error: any) => void;
    onRedirectToLogin?: () => void;
  };
}

常见问题

Q: CLI 生成的配置和手动配置有什么区别？

功能上完全一致。CLI 只是帮你自动生成配置代码，省去手动查找 datasetCode 的麻烦。

👉 如何使用 CLI 生成配置

Q: 标准方式和别名方式该用哪个？

AI 辅助开发（Cursor、Claude 等）→ 推荐标准方式 dataset_xxx，全局唯一不会混淆
纯人工开发 → 可以用别名方式 users，更易读
混合场景 → 两种都可以用，功能完全一致

Q: alias 和 name 有什么区别？

alias：用于代码中访问模型，如 client.models.users
name：用于 UI 显示，如管理后台的模型列表

Q: 旧版本配置如何迁移？

v1.2.0 完全向下兼容旧的对象格式配置，无需立即迁移。但建议在新项目中使用数组格式：

TypeScript

// 旧格式（仍然支持）
registerModels({
  appCode: "my-app",
  models: {
    users: { tableName: "users", datasetCode: "..." },
  },
});

// 新格式（推荐）
registerModels({
  appCode: "my-app",
  models: [
    { datasetCode: "...", tableName: "users", alias: "users" },
  ],
});

下一步

CLI 相关：

🛠️ CLI 安装指南 - 安装 Lovrabet CLI
🚀 5 分钟快速上手 - 从零创建项目
📡 API 集成 - 详细的 lovrabet api pull 用法

SDK 进阶：

🔐 认证配置 - 配置 Token 或 OpenAPI 认证
📊 API 使用指南 - 深入了解 CRUD 操作
🚀 高级功能 - Filter API、SQL API 等

配置详解 ​

为什么需要配置？ ​

快速开始：CLI 自动配置（推荐） ​

第 1 步：拉取配置 ​

第 2 步：使用配置 ​

第 3 步（可选）：使用别名 ​

手动配置（适用于特殊场景） ​

方式 1：预注册配置 ​

方式 2：直接传入配置 ​

模型访问方式详解 ​

标准方式（推荐） ​

别名方式（语法糖） ​

对比总结 ​

进阶配置 ​

多项目配置管理 ​

ClientConfig 扩展选项 ​

动态添加模型 ​

获取模型信息 ​

配置结构参考 ​

ModelsConfig ​

ClientConfig ​

常见问题 ​

Q: CLI 生成的配置和手动配置有什么区别？ ​

Q: 标准方式和别名方式该用哪个？ ​

Q: alias 和 name 有什么区别？ ​

Q: 旧版本配置如何迁移？ ​

下一步 ​

配置详解

为什么需要配置？

快速开始：CLI 自动配置（推荐）

第 1 步：拉取配置

第 2 步：使用配置

第 3 步（可选）：使用别名

手动配置（适用于特殊场景）

方式 1：预注册配置

方式 2：直接传入配置

模型访问方式详解

标准方式（推荐）

别名方式（语法糖）

对比总结

进阶配置

多项目配置管理

ClientConfig 扩展选项

动态添加模型

获取模型信息

配置结构参考

ModelsConfig

ClientConfig

常见问题

Q: CLI 生成的配置和手动配置有什么区别？

Q: 标准方式和别名方式该用哪个？

Q: alias 和 name 有什么区别？

Q: 旧版本配置如何迁移？

下一步