SDK 安装与使用

在 CLI 跑通并创建了 Ontology 模型后，你可以使用 osdk generate 生成强类型的 TypeScript SDK，并在你的前端或 Node.js 应用中使用。

1. 生成项目特有 SDK

# 从后端 URL 生成（推荐，会自动复用 osdk init 的凭据）
osdk generate --out ./src/generated

生成目录结构示例：

src/generated/
├── OntologySdk.ts       # 入口：聚合所有 Repository 与 link
├── Customer.ts          # Customer 对象类型与属性定义
├── CustomerRepository.ts
├── Order.ts
├── OrderRepository.ts
└── index.ts

2. 安装运行时依赖

生成的代码依赖 @loambase/osdk-runtime 提供的基础类。

npm install @loambase/osdk-runtime

3. 初始化 SDK

在你的应用代码中引入生成的 OntologySdk 并实例化：

import { OntologySdk } from './generated/OntologySdk.js';
 
const sdk = new OntologySdk({
  baseUrl: 'https://tenant-1.loambase.com',
  authToken: process.env.PAT_TOKEN, // 你的 PAT
  headers: {
    'X-Workspace-Id': 'workspace-1', // 你的 Workspace ID
  },
});

4. 核心操作示例

写入数据 (Upsert)

// 插入新数据
const customer = await sdk.customer.upsert({
  id: 'c1',
  name: 'Alice',
  age: 30,
});
 
console.log(customer.primaryKey, customer.name, customer.age);
 
// 更新数据（主键相同即更新）
await sdk.customer.upsert({
  id: 'c1',
  name: 'Alice Smith',
  age: 31,
});

查询与过滤

// 查询全部（分页）
const page = await sdk.customer.query().limit(10).execute();
for (const c of page.data) {
  console.log(c.id, c.name, c.age);
}
 
// 过滤查询
const filtered = await sdk.customer
  .query()
  .where('age', 'gt', 25)
  .limit(10)
  .execute();
 
// 多条件 + 排序
const sorted = await sdk.customer
  .query()
  .where('age', 'gte', 18)
  .where('name', 'contains', 'Alice')
  .orderBy('age', 'desc')
  .limit(10)
  .execute();
 
// 聚合统计
const count = await sdk.customer.query().where('age', 'gt', 25).count();

遍历关联对象 (Traverse)

如果在 Schema 中定义了 Customer 到 Order 的关联（Link），生成的 SDK 会提供强类型导航方法：

// 假设已为客户创建了订单
await sdk.order.upsert({ id: 'o1', customer_id: 'c1', total: 99.5, status: 'paid' });
 
// 获取客户
const customer = await sdk.customer.get('c1');
 
// 通过生成的 orders() 方法遍历客户关联的订单
const orders = await customer.orders().load({ limit: 10 });
 
for (const order of orders.data) {
  console.log(order.id, order.total, order.status);
}