---

模型别名配置

本文介绍如何使用人类友好的模型别名来访问数据集，以及如何通过 CLI 自动生成配置。

为什么需要模型别名？

在 Lovrabet 平台中，每个数据集都有一个唯一的 datasetCode（如 8d2dcbae08b54bdd84c00be558ed48df），这是系统自动生成的哈希 ID。

不使用别名时的代码：

// 使用 datasetCode 访问（不易读）
const orders = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();
const customers = await client.models.dataset_a1b2c3d4e5f6789012345678abcdef12.filter();
const products = await client.models.dataset_f9e8d7c6b5a4321098765432fedcba98.filter();

使用别名后的代码：

// 使用别名访问（清晰易读）
const orders = await client.models.orders.filter();
const customers = await client.models.customers.filter();
const products = await client.models.products.filter();

模型别名让代码更加：

• ✅ 可读性强 - 一眼就知道在操作哪个数据表
• ✅ 易于维护 - 不需要记忆复杂的哈希 ID
• ✅ 团队协作友好 - 代码审查和交接更轻松

两种配置方式

方式一：使用 CLI 自动生成（推荐）

使用 lovrabet api pull 命令自动生成配置文件，无需手动编写。

lovrabet api pull

💡 前置条件使用前请确保已完成 CLI 安装和登录配置。

执行后会在项目中生成两个文件：

src/api/api.ts - 模型配置文件：

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

export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
  appCode: "your-app-code",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "orders",
      alias: "orders"
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "customers",
      alias: "customers"
    },
    {
      datasetCode: "f9e8d7c6b5a4321098765432fedcba98",
      tableName: "products",
      alias: "products"
    },
    // ... 自动生成所有数据集
  ],
};

registerModels(LOVRABET_MODELS_CONFIG);

src/api/client.ts - 封装好的客户端：

import { createClient } from "@lovrabet/sdk";
import "./api"; // 自动注册配置

export const lovrabetClient = createClient();

在项目中使用

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

// 直接使用别名访问
const orders = await lovrabetClient.models.orders.filter();
const customers = await lovrabetClient.models.customers.filter();
const products = await lovrabetClient.models.products.filter();

💡 CLI 详细使用指南更多 CLI 使用方法，请参考 自动生成 SDK 配置。

方式二：手动配置

如果不使用 CLI，也可以手动配置模型别名。

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

const client = createClient({
  appCode: "your-app-code",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "orders",
      alias: "orders"
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "customers",
      alias: "customers"
    },
  ],
});

// 使用别名访问
const orders = await client.models.orders.filter();

别名命名规则

CLI 自动生成的命名规则

CLI 会自动将数据表名转换为 camelCase 格式的别名：

数据表名	生成的别名
orders	orders
order_items	orderItems
user_profile	userProfile
sales_records	salesRecords
product_categories	productCategories

手动配置的命名建议

如果手动配置别名，建议遵循以下规则：

1. 使用 camelCase - 与 JavaScript 命名习惯一致
2. 语义清晰 - 别名应该能清楚表达数据表的用途
3. 避免冲突 - 确保别名在项目中唯一
4. 保持简洁 - 避免过长的别名

// ✅ 好的别名
{ alias: "orders" }
{ alias: "orderItems" }
{ alias: "userProfile" }

// ❌ 不推荐的别名
{ alias: "o" }  // 太简短，不清晰
{ alias: "order_items" }  // 使用了下划线
{ alias: "theOrderItemsTable" }  // 太冗长

访问方式对比

配置别名后，SDK 支持三种访问方式：

// 方式 1：使用别名（推荐）
client.models.orders.filter()

// 方式 2：使用 dataset_ 前缀 + datasetCode
client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter()

// 方式 3：使用数组索引访问（不推荐）
client.models["dataset_8d2dcbae08b54bdd84c00be558ed48df"].filter()

三种方式功能完全一致，但强烈推荐使用别名方式，代码更清晰易读。

TypeScript 类型支持

使用别名时，TypeScript 会提供完整的类型提示和自动补全。

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

// TypeScript 会自动提示所有可用的模型别名
lovrabetClient.models.  // 输入 . 后会显示：orders, customers, products...

// 类型安全的方法调用
const orders = await lovrabetClient.models.orders.filter({
  where: { status: { $eq: 'pending' } },  // 完整的类型提示
  pageSize: 20,
});

更新配置

当 Lovrabet 工作台有变化时（新增/删除数据表），需要重新生成配置。

使用 CLI 更新

lovrabet api pull

CLI 会自动：

• 添加新的数据集配置
• 移除已删除的数据集
• 更新变更的数据集信息

手动更新

如果是手动配置，需要：

1. 在 Lovrabet 工作台查看数据集列表
2. 复制新数据集的 datasetCode
3. 在配置文件中添加新的模型配置

常见问题

Q: 别名和 datasetCode 可以同时使用吗？

可以。配置别名后，两种方式都可以使用：

// 使用别名
await client.models.orders.filter();

// 使用 datasetCode（仍然有效）
await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

Q: 别名冲突怎么办？

如果两个数据表生成的别名相同（如 user 和 users 都可能生成 user），CLI 会自动处理冲突。

手动配置时，确保每个别名唯一：

models: [
  { datasetCode: "xxx", tableName: "user", alias: "user" },
  { datasetCode: "yyy", tableName: "users", alias: "users" },  // 不同的别名
]

Q: 可以不配置别名吗？

可以。如果不配置别名，仍然可以使用 dataset_ 前缀访问：

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  models: [
    { datasetCode: "8d2dcbae08b54bdd84c00be558ed48df", tableName: "orders" },
    // 没有配置 alias
  ],
});

// 使用 datasetCode 访问
await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

但强烈建议配置别名以提升代码可读性。

Q: 别名可以和表名不同吗？

可以。别名是完全自定义的：

models: [
  {
    datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
    tableName: "t_order",  // 数据库表名
    alias: "orders"        // 自定义别名（更友好）
  },
]

Q: 什么时候需要重新拉取配置？

以下情况需要重新执行 lovrabet api pull：

• ✅ 新增了数据表
• ✅ 删除了数据表
• ✅ 数据表重命名
• ❌ 数据表字段变更（不需要重新拉取）
• ❌ 数据表数据变更（不需要重新拉取）

相关文档

• 自动生成 SDK 配置 - CLI 详细使用指南
• SDK 配置指南 - 完整的配置说明
• 快速开始 - SDK 基础使用
• TypeScript 支持 - 类型安全开发