API 参考手册

完整的 Lovrabet SDK API 参考文档，包含所有类和方法的详细说明。

🏗️ 核心架构

Lovrabet SDK 采用模块化架构设计，主要由以下几个核心组件构成：

LovrabetClient (客户端)
├── models (模型访问器) → ModelManager (模型管理器)
├── AuthManager (认证管理器)
└── HttpClient (HTTP 客户端)
    ├── AuthManager (依赖)
    └── ErrorHandler (错误处理器)

ModelManager (模型管理器)
└── BaseModel[] (模型实例缓存)
    └── HttpClient (依赖)

📋 核心类型定义

ModelConfig

单个模型配置：

interface ModelConfig {
  tableName: string; // 数据表名称（必填）
  datasetCode: string; // 数据集代码（必填，唯一标识）
  name?: string; // 显示名称（可选，用于 UI 展示）
  alias?: string; // 别名（可选，用于 client.models.alias 访问）
  dbName?: string; // 数据库名称（可选，用于区分不同数据库）
}

ModelsConfig

模型集合配置（支持数组和对象两种格式）：

interface ModelsConfig {
  appCode: string; // 应用标识码
  models: ModelConfig[] | Record<string, ModelConfig>; // 模型配置（数组或对象格式）
}

数组格式（推荐）：

const config: ModelsConfig = {
  appCode: "my-app",
  models: [
    { datasetCode: "xxx", tableName: "users", alias: "users" },
    { datasetCode: "yyy", tableName: "orders", alias: "orders" },
  ],
};

对象格式（向下兼容）：

const config: ModelsConfig = {
  appCode: "my-app",
  models: {
    Users: { datasetCode: "xxx", tableName: "users" },
    Orders: { datasetCode: "yyy", tableName: "orders" },
  },
};

ClientConfig

客户端完整配置：

interface ClientConfig {
  // 基础配置
  appCode?: string; // 应用标识码
  serverUrl?: string; // 服务器地址
  env?: Environment; // 运行环境

  // 认证配置
  token?: string; // 用户令牌（Bearer 认证）
  timestamp?: number; // 与 token 配对的时间戳（OpenAPI 模式必需）
  accessKey?: string; // OpenAPI 访问密钥（签名认证）
  secretKey?: string; // OpenAPI 密钥（签名认证）
  requiresAuth?: boolean; // 是否需要认证，默认 true

  // 模型配置
  models?: ModelConfig[] | Record<string, ModelConfig>; // 模型配置
  apiConfigName?: string; // 引用已注册的配置名称

  // 扩展选项
  options?: {
    timeout?: number; // 请求超时时间（毫秒）
    retryCount?: number; // 重试次数
    debug?: boolean; // 调试模式，打印请求详情 (v1.1.14+)
    onError?: (error: any) => void; // 错误回调
    onRedirectToLogin?: () => void; // 登录重定向回调
  };
}

ListParams

列表查询参数：

interface ListParams {
  currentPage?: number; // 当前页码 (默认: 1)
  pageSize?: number; // 页面大小 (默认: 20)
  [key: string]: any; // 其他查询参数
}

ListResponse

分页响应格式：

interface ListResponse<T> {
  tableData: T[]; // 数据列表
  total: number; // 总记录数
  currentPage: number; // 当前页码
  pageSize: number; // 页面大小
}

SortOrder v1.1.16+

排序方向枚举：

enum SortOrder {
  ASC = "asc",   // 升序
  DESC = "desc", // 降序
}

使用示例：

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

// 使用枚举值（推荐）
const sortList = [{ createTime: SortOrder.DESC }, { name: SortOrder.ASC }];

// 或直接使用字符串
const sortList = [{ createTime: "desc" }, { name: "asc" }];

SortList v1.1.16+

排序配置列表类型：

type SortList = Record<string, "asc" | "desc">[];

排序列表采用简洁的 key-value 格式，每个对象表示一个排序字段：

• key: 字段名称
• value: 排序方向（"asc" 或 "desc"）

使用示例：

import { SortOrder, type SortList } from "@lovrabet/sdk";

// 单字段排序
const sort1: SortList = [{ id: SortOrder.DESC }];

// 多字段排序
const sort2: SortList = [
  { priority: SortOrder.DESC }, // 第一优先级：按优先级降序
  { createTime: SortOrder.DESC }, // 第二优先级：按创建时间降序
  { name: SortOrder.ASC }, // 第三优先级：按名称升序
];

// 使用排序
const users = await client.models.users.filter(
  { currentPage: 1, pageSize: 20 },
  sort2
);

SelectOption v1.1.18+

下拉选项数据格式：

interface SelectOption {
  label: string; // 显示文本
  value: string; // 选项值
}

这是 getSelectOptions() 方法返回的标准格式，可直接用于前端组件：

const options: SelectOption[] = [
  { label: "张三", value: "user001" },
  { label: "李四", value: "user002" },
];

// 在 React Select 组件中使用
<Select>
  {options.map((opt) => (
    <Option key={opt.value} value={opt.value}>
      {opt.label}
    </Option>
  ))}
</Select>;

SelectOptionsParams v1.1.18+

下拉选项查询参数：

interface SelectOptionsParams {
  code: string; // 用作选项值的字段名
  label: string; // 用作显示文本的字段名
}

使用示例：

// 从用户表获取下拉选项
const params: SelectOptionsParams = {
  code: "user_id", // 数据表的 user_id 字段作为 value
  label: "user_name", // 数据表的 user_name 字段作为 label
};

const options = await client.models.users.getSelectOptions(params);
// 返回: [{ label: '张三', value: 'user001' }, ...]

// 在订单状态选择中使用
const statusParams: SelectOptionsParams = {
  code: "status_code",
  label: "status_name",
};
const statusOptions = await client.models.orderStatus.getSelectOptions(
  statusParams
);

🏭 工厂函数

createClient()

创建 SDK 客户端实例，支持多种配置方式。

函数签名

function createClient(
  config?: Partial<ClientConfig> | ModelsConfig | string
): LovrabetClient;

参数说明

参数	类型	默认值	说明
config	Partial<ClientConfig> | ModelsConfig | string	'default'	客户端配置

使用方式

1. 使用预注册配置名称

const client = createClient("default");
const prodClient = createClient("prod");

2. 直接传入模型配置

const client = createClient({
  appCode: "my-app",
  models: {
    Users: { tableName: "users", datasetCode: "user-id" },
    Posts: { tableName: "posts", datasetCode: "post-id" },
  },
});

3. 使用完整客户端配置

const client = createClient({
  appCode: "my-app",
  token: "your-token",
  models: {
    users: { tableName: "users", datasetCode: "8d2dcbae08b54bdd84c00be558ed48df" },
  },
  options: {
    timeout: 30000,
    retryCount: 3,
  },
});

4. 引用配置但覆盖部分选项

const client = createClient({
  apiConfigName: "default", // 使用预注册的 default 配置
  token: "custom-token", // 但使用自定义 token
});

返回值

返回 LovrabetClient 实例。

📱 LovrabetClient 类

SDK 的主要客户端类，提供模型访问和配置管理功能。

Client 对象结构

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  models: [
    { tableName: "users", datasetCode: "xxx", alias: "users" },
  ],
});

// client 包含以下命名空间：
client.models  // 模型访问器
client.sql     // SQL 客户端 (v1.1.19+)
client.bff      // BFF 客户端 (v1.2.0+)
client.user     // User 客户端
client.api      // API 命名空间（别名，向后兼容）

属性

models

模型访问器，支持两种访问方式：

public models: { [modelName: string]: BaseModelMethods }

访问方式：

// 标准方式（推荐）- 使用 dataset_ 前缀 + datasetCode
const data1 = await client.models.dataset_xxx.filter();

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

sql v1.1.19+

SQL 客户端，用于执行已注册的自定义 SQL 查询：

public readonly sql: SqlClient

API 方法：

方法	说明
execute({ sqlCode, params })	执行 SQL 查询（对象参数，推荐）
execute(sqlCode, params)	执行 SQL 查询（直接传参，兼容）

使用示例：

// 推荐：对象参数
const result = await client.sql.execute({
  sqlCode: 'fc8e7777-06e3847d',
  params: { userId: '123' }
});

// 兼容：直接传参
const result = await client.sql.execute('fc8e7777-06e3847d', { userId: '123' });

// 别名方式（向后兼容，不推荐）
const result = await client.api.executeSql('fc8e7777-06e3847d', { userId: '123' });

// 检查执行结果
if (result.execSuccess && result.execResult) {
  result.execResult.forEach(row => console.log(row));
}

返回类型：

interface SqlExecuteResult<T> {
  execSuccess: boolean;    // SQL 执行是否成功
  execResult?: T[];        // 查询结果数组
}

bff v1.2.0+

BFF 客户端，用于调用 Backend For Frontend 端点：

public readonly bff: BffClient

API 方法：

方法	说明
execute({ scriptName, params, options })	调用后端函数

使用示例：

// 无参数调用
const result = await client.bff.execute({
  scriptName: 'getUserDashboard'
});

// 带参数调用
const result = await client.bff.execute({
  scriptName: 'calculatePrice',
  params: { productId: '123', quantity: 10 }
});

// 带类型提示
interface DashboardData {
  userCount: number;
  orderCount: number;
}
const dashboard = await client.bff.execute<DashboardData>({
  scriptName: 'getUserDashboard'
});

// 别名方式（向后兼容，不推荐）
const result = await client.api.bff('calculatePrice', {
  productId: '123',
  quantity: 10
});

返回值： 直接返回业务数据（已在 SDK 中从 data 字段提取）

错误处理： HTTP 错误会抛出 LovrabetError

user

User 客户端，用于获取用户信息：

public readonly user: UserClient

API 方法：

方法	说明
getList()	获取用户列表

使用示例：

const userList = await client.user.getList();
console.log(userList);

api

API 命名空间，提供向后兼容的别名访问方式：

public readonly api: ApiNamespace

推荐方式 vs 别名：

推荐方式	别名（兼容）
client.sql.execute()	client.api.executeSql()
client.bff.execute()	client.api.bff()
client.user.getList()	client.api.getUserList()

开发建议

推荐使用 client.sql、client.bff、client.user 命名空间，代码更清晰，类型提示更友好。

方法

setToken()

设置用户认证令牌。

setToken(token: string, timestamp?: number): void

参数：

• token - 用户认证令牌
• timestamp - 与 token 配对的时间戳（可选，OpenAPI 模式需要）

使用示例：

// WebAPI 模式（Cookie 认证）
client.setToken("your-new-token");

// OpenAPI 模式（需要 timestamp）
client.setToken("your-new-token", Date.now());

getConfig()

获取客户端配置信息。

getConfig(): ClientConfig

返回值：

• 返回当前客户端配置对象

使用示例：

const config = client.getConfig();
console.log("App Code:", config.appCode);

getBaseUrl()

获取 API 基础地址。

getBaseUrl(): string

返回值：

• 返回完整的 API 基础地址

使用示例：

const baseUrl = client.getBaseUrl();
// 输出: https://api.lovrabet.com/api

getModelList()

获取所有可用模型名称列表。

getModelList(): string[]

返回值：

• 返回模型名称数组

使用示例：

const modelNames = client.getModelList();
console.log("可用模型:", modelNames);
// 输出: ['Users', 'Posts', 'Comments']

getModel()

通过索引或名称获取模型实例。

getModel(indexOrName: number | string): BaseModelMethods

参数：

• indexOrName - 模型索引（从 0 开始）或模型名称

返回值：

• 返回 BaseModel 实例

使用示例：

// 通过索引获取第一个模型
const firstModel = client.getModel(0);
const data = await firstModel.filter();

// 通过名称获取模型
const userModel = client.getModel("Users");
const user = await userModel.getOne(123);

📊 BaseModel 类

所有数据模型的基类，提供完整的 CRUD 操作接口。

方法

getList()

获取数据列表，支持分页查询和多字段排序。

async getList<T = any>(
  params?: ListParams,
  sortList?: SortList
): Promise<ListResponse<T>>

参数：

• params - 查询参数（可选）
• sortList - 排序配置列表（可选），支持多字段排序

返回值：

• 返回分页数据响应

使用示例：

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

// 基础查询
const response = await client.models.users.filter();

// 分页查询
const response = await client.models.users.filter({
  currentPage: 2,
  pageSize: 50,
});

// 带条件查询
const response = await client.models.users.filter({
  currentPage: 1,
  pageSize: 20,
  name: "John", // 自定义查询条件
  status: "active",
});

// 带排序查询（单字段）
const response = await client.models.users.filter(
  { currentPage: 1, pageSize: 20 },
  [{ createTime: SortOrder.DESC }] // 按创建时间降序
);

// 带排序查询（多字段）
const response = await client.models.products.filter(
  { currentPage: 1, pageSize: 20 },
  [
    { priority: SortOrder.DESC }, // 优先按优先级降序
    { createTime: SortOrder.DESC }, // 再按创建时间降序
    { name: SortOrder.ASC }, // 最后按名称升序
  ]
);

console.log("用户列表:", response.tableData);
console.log("总数:", response.total);
console.log("当前页:", response.currentPage);

filter() v1.1.21+

高级过滤查询方法，支持复杂条件、字段选择、排序和分页（推荐使用）。

async filter<T = any>(params?: FilterParams): Promise<ListResponse<T>>

参数：

• params - Filter 查询参数（可选）
  • where - 查询条件，支持 $eq、$ne、$gte、$lte、$in、$contain 等操作符
  • select - 选择返回的字段列表
  • orderBy - 排序规则
  • currentPage - 当前页码
  • pageSize - 每页数量

返回值：

• 返回分页数据响应

快速示例：

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

// 复杂条件查询
const response = await client.models.users.filter({
  where: {
    $and: [
      { age: { $gte: 18, $lte: 45 } },           // 年龄范围
      { country: { $in: ['中国', '美国'] } },     // 国家列表
      { name: { $contain: 'hello' } }             // 名称包含
    ]
  },
  select: ['id', 'name', 'age', 'country'],      // 只返回这些字段
  orderBy: [{ createTime: SortOrder.DESC }],     // 按创建时间降序
  currentPage: 1,
  pageSize: 20
});

详细使用指南

filter API 提供了强大的查询能力，支持所有条件操作符（$eq、$ne、$gte、$lte、$in、$contain、$startWith、$endWith）和逻辑连接符（$and、$or）。详见 Filter API 完整指南。

操作限制

filter() 操作仅 WebAPI 模式（Cookie 认证）支持。OpenAPI 模式暂不支持此功能。

getOne()

获取单条记录。

async getOne<T = any>(id: string | number): Promise<T>

参数：

• id - 记录 ID

返回值：

• 返回单条记录数据

使用示例：

const user = await client.models.users.getOne(123);
console.log("用户信息:", user);

// 类型安全的用法
interface User {
  id: number;
  name: string;
  email: string;
}

const user = await client.models.users.getOne<User>(123);
console.log("用户名:", user.name);

create()

创建新记录。

async create<T = any>(data: Record<string, any>): Promise<T>

参数：

• data - 要创建的记录数据

返回值：

• 返回创建后的记录数据

使用示例：

const newUser = await client.models.users.create({
  name: "John Doe",
  email: "john@example.com",
  age: 25,
});

console.log("新建用户 ID:", newUser.id);

update()

更新现有记录。

async update<T = any>(id: string | number, data: Record<string, any>): Promise<T>

参数：

• id - 记录 ID
• data - 要更新的数据

返回值：

• 返回更新后的记录数据

使用示例：

const updatedUser = await client.models.users.update(123, {
  name: "Jane Doe",
  email: "jane@example.com",
});

console.log("更新后的用户:", updatedUser);

delete()

删除记录。

async delete(id: string | number): Promise<void>

参数：

• id - 要删除的记录 ID

返回值：

• 无返回值

使用示例：

await client.models.users.delete(123);
console.log("用户删除成功");

操作限制

delete() 操作仅 WebAPI 模式（Cookie 认证）支持。OpenAPI 模式暂不支持此操作。

getSelectOptions() v1.1.18+

获取数据表的下拉选项数据。

async getSelectOptions(params: SelectOptionsParams): Promise<SelectOption[]>

参数：

• params - 选项配置参数
  • code - 用作选项值的字段名
  • label - 用作显示文本的字段名

返回值：

• 返回标准化的选项数组，格式为 { label: string, value: string }[]

使用示例：

// 获取用户下拉选项
const userOptions = await client.models.users.getSelectOptions({
  code: "user_id",
  label: "user_name",
});

console.log(userOptions);
// [
//   { label: '张三', value: 'user001' },
//   { label: '李四', value: 'user002' }
// ]

// 在 React Select 组件中使用
import { Select } from "antd";

function UserSelector() {
  const [options, setOptions] = useState([]);

  useEffect(() => {
    const loadOptions = async () => {
      const data = await client.models.users.getSelectOptions({
        code: "id",
        label: "name",
      });
      setOptions(data);
    };
    loadOptions();
  }, []);

  return (
    <Select placeholder="选择用户">
      {options.map((opt) => (
        <Option key={opt.value} value={opt.value}>
          {opt.label}
        </Option>
      ))}
    </Select>
  );
}

// 订单状态选择器
const statusOptions = await client.models.orderStatus.getSelectOptions({
  code: "status_code",
  label: "status_name",
});

// 部门选择器
const deptOptions = await client.models.departments.getSelectOptions({
  code: "dept_id",
  label: "dept_name",
});

操作限制

getSelectOptions() 操作仅 WebAPI 模式（Cookie 认证）支持。OpenAPI 模式暂不支持此功能。

getConfig()

获取模型配置信息。

getConfig(): ModelConfig

返回值：

• 返回模型配置对象

使用示例：

const config = client.models.users.getConfig();
console.log("表名:", config.tableName);
console.log("数据集 ID:", config.datasetCode);

getModelName()

获取模型名称。

getModelName(): string

返回值：

• 返回模型名称

使用示例：

const modelName = client.models.users.getModelName();
console.log("模型名称:", modelName); // 输出: Users

🔌 ApiNamespace 类 v1.1.19+

提供自定义 SQL 查询等 API 操作，通过 client.api 命名空间访问。

方法

executeSql()

执行平台上配置的自定义 SQL 查询。

async executeSql<T = Record<string, any>>(
  sqlCode: string | number,
  params?: Record<string, string | number>
): Promise<SqlExecuteResult<T>>

参数：

• sqlCode - SQL 代码（格式："appCode-sqlId" 或数字 ID）
• params - SQL 参数对象（可选），用于参数化查询

返回值：

• 返回 SQL 执行结果，包含 execSuccess 和 execResult 字段

类型定义：

interface SqlExecuteResult<T> {
  execSuccess: boolean; // SQL 执行是否成功
  execResult?: T[]; // 查询结果数组（仅成功时存在）
}

使用示例：

// 基础查询
const data = await client.api.executeSql("fc8e7777-06e3847d");

if (data.execSuccess && data.execResult) {
  console.log("查询结果:", data.execResult);
}

// 参数化查询（防止 SQL 注入）
const data = await client.api.executeSql("fc8e7777-xxxxx", {
  userId: "123",
  startDate: "2025-01-01",
});

// 带类型提示
interface PageStat {
  creation_date: string;
  page_count: number;
}

const data = await client.api.executeSql<PageStat>("fc8e7777-06e3847d");
if (data.execSuccess && data.execResult) {
  data.execResult.forEach((stat) => {
    console.log(`日期: ${stat.creation_date}, 数量: ${stat.page_count}`);
  });
}

详细使用指南

SQL API 支持复杂统计查询、关联查询、自定义报表等场景。详见 SQL API 使用指南。

🗂️ 配置管理 API

registerModels()

注册模型配置到全局注册表。

function registerModels(config: ModelsConfig, name?: string): void;

参数：

• config - 模型配置对象
• name - 配置名称（默认: 'default'）

使用示例：

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

// 注册默认配置
registerModels({
  appCode: "my-app",
  models: {
    Users: { tableName: "users", datasetCode: "user-id" },
    Posts: { tableName: "posts", datasetCode: "post-id" },
  },
});

// 注册生产环境配置
registerModels(
  {
    appCode: "my-app-prod",
    models: {
      Users: { tableName: "users", datasetCode: "prod-user-id" },
    },
  },
  CONFIG_NAMES.PROD
);

getRegisteredModels()

获取已注册的模型配置。

function getRegisteredModels(name: string): ModelsConfig | undefined;

参数：

• name - 配置名称

返回值：

• 返回配置对象或 undefined

使用示例：

const config = getRegisteredModels("default");
if (config) {
  console.log("App Code:", config.appCode);
}

getRegisteredConfigNames()

获取所有已注册的配置名称。

function getRegisteredConfigNames(): string[];

返回值：

• 返回配置名称数组

使用示例：

const names = getRegisteredConfigNames();
console.log("已注册配置:", names);
// 输出: ['default', 'prod', 'dev']

🔗 常量定义

CONFIG_NAMES

预定义的配置名称常量：

export const CONFIG_NAMES = {
  DEFAULT: "default",
  PROD: "prod",
  DEV: "dev",
  TEST: "test",
} as const;

ENVIRONMENTS

环境类型常量：

export const ENVIRONMENTS = {
  ONLINE: "online",
} as const;

DEFAULTS

默认值常量：

export const DEFAULTS = {
  ENV: "online",
  TIMEOUT: 30000,
  RETRY_COUNT: 3,
  PAGE_SIZE: 20,
  CURRENT_PAGE: 1,
} as const;

📋 完整使用示例

基础 CRUD 操作

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

// 1. 注册配置
registerModels({
  appCode: "copybook-app",
  models: {
    Users: { tableName: "users", datasetCode: "user-dataset-id" },
    Characters: { tableName: "characters", datasetCode: "char-dataset-id" },
  },
});

// 2. 创建客户端
const client = createClient();

// 3. 完整的 CRUD 操作示例
async function crudExample() {
  // 创建用户
  const newUser = await client.models.users.create({
    name: "张三",
    email: "zhangsan@example.com",
    grade: 3,
  });
  console.log("创建用户:", newUser);

  // 获取用户列表
  const userList = await client.models.users.filter({
    currentPage: 1,
    pageSize: 10,
    grade: 3, // 筛选三年级学生
  });
  console.log("用户列表:", userList.tableData);

  // 获取单个用户
  const user = await client.models.users.getOne(newUser.id);
  console.log("用户详情:", user);

  // 更新用户
  const updatedUser = await client.models.users.update(user.id, {
    email: "zhangsan.new@example.com",
  });
  console.log("更新用户:", updatedUser);

  // 删除用户
  await client.models.users.delete(user.id);
  console.log("删除成功");
}

crudExample();

多环境配置示例

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

// 开发环境配置
registerModels(
  {
    appCode: "app-dev-123",
    models: {
      Users: { tableName: "users", datasetCode: "dev-user-id" },
    },
  },
  CONFIG_NAMES.DEV
);

// 生产环境配置
registerModels(
  {
    appCode: "app-prod-456",
    models: {
      Users: { tableName: "users", datasetCode: "prod-user-id" },
    },
  },
  CONFIG_NAMES.PROD
);

// 根据环境创建不同客户端
const isDevelopment = process.env.NODE_ENV === "development";
const client = createClient(
  isDevelopment ? CONFIG_NAMES.DEV : CONFIG_NAMES.PROD
);

认证配置示例

// Token 认证
const client = createClient({
  apiConfigName: "default",
  token: "your-user-token",
});

// OpenAPI 密钥认证
const apiClient = createClient({
  apiConfigName: "default",
  accessKey: "your-access-key",
  secretKey: "your-secret-key",
});

// 动态设置 Token
client.setToken("new-token-after-login");

动态模型访问示例

// 获取第一个可用模型
const firstModel = client.getModel(0);
const data = await firstModel.filter();

// 遍历所有模型
const modelNames = client.getModelList();
for (const name of modelNames) {
  const model = client.getModel(name);
  const config = model.getConfig();
  console.log(`模型 ${name}: ${config.tableName}`);
}

🚨 错误处理

SDK 提供统一的错误处理机制：

try {
  const users = await client.models.users.filter();
} catch (error) {
  console.error("API 调用失败:", error);

  // 检查错误类型
  if (error.status === 401) {
    console.log("认证失败，需要重新登录");
  } else if (error.status === 403) {
    console.log("权限不足");
  } else if (error.status >= 500) {
    console.log("服务器错误");
  }
}

safe 函数 v1.2.10+

safe 函数提供无 try-catch 的错误处理方式：

import { safe, type SafeResult } from "@lovrabet/sdk";

const { data, error } = await safe(() => client.models.users.filter());

if (error) {
  console.error("失败:", error.message);
  return;
}
console.log("成功:", data);

类型定义：

interface SafeResult<T> {
  data: T | null;
  error: LovrabetError | null;
}

function safe<T>(
  fn: Promise<T> | (() => Promise<T>)
): Promise<SafeResult<T>>;

详见 错误处理指南。

⚡ 性能优化建议

1. 模型实例复用

// ✅ 推荐：复用客户端实例
const client = createClient();
export { client };

// ❌ 避免：重复创建客户端
function getUsers() {
  const client = createClient(); // 每次都创建新实例
  return client.models.users.filter();
}

2. 批量操作

// ✅ 推荐：批量创建
const users = [
  { name: "用户1", email: "user1@example.com" },
  { name: "用户2", email: "user2@example.com" },
];

const promises = users.map((user) => client.models.users.create(user));
const results = await Promise.all(promises);

3. 合理的分页大小

// ✅ 推荐：根据实际需求设置合理的页面大小
const users = await client.models.users.filter({
  currentPage: 1,
  pageSize: 50, // 根据 UI 显示需求设置
});

---

📚 相关文档

核心文档

• 快速开始 - 5 分钟快速上手
• 配置详解 - 详细配置说明
• 认证配置 - 认证方式配置
• 实际应用示例 - 完整集成示例
• 故障排查 - 常见问题解决

API 专项文档

• Filter API 完整指南 - 高级查询详细说明
• SQL API 使用指南 - 自定义 SQL 查询
• 错误处理指南 - 错误处理最佳实践

有问题？查看 故障排查文档 或联系技术支持。