跳到主要内容

配置详解

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

为什么需要配置？​

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

// ❌ 没有配置：每次调用都要手动填写 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 步：拉取配置​

在项目根目录执行：

lovrabet api pull

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

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

// 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 步：使用配置​

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

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 别名：

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

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

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

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

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

方式 1：预注册配置​

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

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：直接传入配置​

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

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 访问：

// 格式：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，可以用更短的名称访问：

// 格式：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

进阶配置​

多项目配置管理​

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

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 扩展选项​

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

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";
    },
  },
});

动态添加模型​

运行时动态添加新模型：

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

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

获取模型信息​

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

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

配置结构参考​

ModelsConfig​

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

ClientConfig​

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 完全向下兼容旧的对象格式配置，无需立即迁移。但建议在新项目中使用数组格式：

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

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

下一步​

CLI 相关：

SDK 进阶：