跳到主要内容

WebAPI 与 OpenAPI 对比

Lovrabet 数据平台提供了两套完整的 API 体系：WebAPI 和 OpenAPI。它们各有特点,适用于不同的业务场景。本文将深入对比两者的差异,帮助您选择最适合的接入方式。

核心差异总览​

对比维度WebAPI (Cookie 模式)OpenAPI (Token/AccessKey 模式)
认证方式浏览器 Cookie（用户登录态）HMAC-SHA256 签名 (Token/AccessKey)
适用环境仅浏览器端Node.js 服务端 + 浏览器端
使用场景已登录用户访问私有数据服务端集成、第三方系统、公开数据访问
API 路径格式/api/{appCode}/{datasetCode}/{method}/openapi/data/{method}
请求体结构直接传递参数 { currentPage, pageSize }需要包装 { appCode, datasetCode, paramMap }
认证头无需特殊 Header必须提供 X-Token, X-Time-Stamp 等
安全机制依赖 Lovrabet 平台登录态独立的签名验证 + Token 时效控制
数据权限基于用户登录权限基于应用授权范围
跨域处理需要 credentials: 'include'标准 CORS

业界对比与定位​

WebAPI - 类似 "会话 API"​

WebAPI 类似于传统 Web 应用的 Session-based API,在业界常见于:

  • SaaS 平台的用户界面 API - 如 Salesforce、Notion 的 Web 应用内 API
  • 内嵌式集成 - 通过 iframe 嵌入到母应用中,共享登录态
  • 单页应用 (SPA) - React/Vue 应用调用自家后端接口

特点:

  • 强依赖用户登录状态
  • 无需管理密钥和签名
  • 权限继承用户角色
  • 适合 用户级操作

OpenAPI - 类似 "RESTful API"​

OpenAPI 遵循业界标准的 API-Key based 认证模式,类似于:

  • AWS API - 使用 Access Key + Secret Key 进行 HMAC 签名
  • Stripe API - 使用 API Key 进行认证
  • GitHub API - 使用 Personal Access Token
  • Twilio API - 使用 Account SID + Auth Token

特点:

  • 独立认证体系,不依赖用户登录
  • 支持服务端到服务端(S2S)调用
  • 适合系统集成和自动化
  • 适合 应用级操作

详细对比​

1. 认证机制​

WebAPI - Cookie 认证​

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

// ✅ 无需提供任何认证信息
const client = createClient({
  appCode: "your-app-code",
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// 自动使用浏览器 Cookie,请求会包含 credentials: 'include'
const users = await client.models.users.filter();

优点:

  • 零配置,无需管理密钥
  • 自动继承用户权限
  • 适合快速开发

缺点:

  • 仅限浏览器环境
  • 必须在 Lovrabet 域名下或配置 CORS
  • 无法用于服务端或第三方集成

OpenAPI - Token/AccessKey 认证​

模式 1: 服务端使用 AccessKey

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

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // ⚠️ 只能在服务端使用
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// SDK 自动生成签名: HMAC-SHA256(accessKey + timestamp + appCode + datasetCode)
const users = await client.models.users.filter();

模式 2: 浏览器使用预生成 Token

// 服务端生成 Token
import { generateOpenApiToken } from "@lovrabet/sdk";

const { token, timestamp, expiresAt } = await generateOpenApiToken({
  appCode: "your-app-code",
  datasetCode: "ds-001",
  accessKey: process.env.LOVRABET_ACCESS_KEY,
});

// 浏览器使用 Token
const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

优点:

  • 支持服务端和浏览器端
  • 独立认证,不依赖用户登录
  • 适合系统集成和自动化
  • 更细粒度的权限控制

缺点:

  • 需要妥善保管 AccessKey
  • Token 有时效性,需要刷新
  • 浏览器端需要额外的 Token 生成接口

2. API 路径差异​

WebAPI 路径结构​

/api/{appCode}/{datasetCode}/{method}

示例:

POST /api/app-c2dd52a2/0fefba76fe29440194841f4825df53ff/getList
POST /api/app-c2dd52a2/0fefba76fe29440194841f4825df53ff/getOne
POST /api/app-c2dd52a2/0fefba76fe29440194841f4825df53ff/create

特点:

  • RESTful 风格,路径包含资源标识
  • 方法名使用 camelCase (getList, getOne)
  • 路径中已包含 appCode 和 datasetCode

OpenAPI 路径结构​

/openapi/data/{method}        # 数据操作
/openapi/dataset/{method}     # 数据集元信息

示例:

POST /openapi/data/get-list       # 批量查询
POST /openapi/data/get-one        # 单条查询
POST /openapi/data/create         # 创建数据

特点:

  • 统一的 API 端点
  • 方法名使用 kebab-case (get-list, get-one)
  • appCode 和 datasetCode 在请求体和 Header 中传递

3. 请求体结构差异​

WebAPI 请求体​

// getList 请求
POST /api/app-c2dd52a2/ds-001/getList
Content-Type: application/json

{
  "currentPage": 1,
  "pageSize": 20,
  "status": "active",
  "ytSortList": [
    { "gmt_create": "desc" }
  ]
}

特点:

  • 直接传递业务参数,无需包装
  • 参数扁平化,简洁明了

OpenAPI 请求体​

// getList 请求
POST /openapi/data/get-list
Content-Type: application/json
X-Time-Stamp: 1758903130713
X-App-Code: app-c2dd52a2
X-Dataset-Code: 0fefba76fe29440194841f4825df53ff
X-Token: jdqqGtzecF2I6FIW...

{
  "appCode": "app-c2dd52a2",
  "datasetCode": "0fefba76fe29440194841f4825df53ff",
  "paramMap": {
    "currentPage": 1,
    "pageSize": 20,
    "status": "active",
    "ytSortList": [
      { "gmt_create": "desc" }
    ]
  }
}

特点:

  • 需要包装为 { appCode, datasetCode, paramMap } 结构
  • 业务参数放在 paramMap 中
  • 同时在 Header 和 Body 中传递认证信息
SDK 自动处理差异

使用 SDK 时,无需关心底层差异。SDK 会根据配置自动选择 WebAPI 或 OpenAPI 模式,调用方式完全相同:

const users = await client.models.users.filter({
  currentPage: 1,
  pageSize: 20,
});

使用场景选择指南​

场景 1: 基于 Lovrabet 开发个性化页面（微前端集成）​

业务场景:

您在 Lovrabet 平台上搭建了一套业务系统（如 CRM、ERP、项目管理等），系统基本功能已满足需求，但希望针对特定业务场景开发一些定制化页面，并无缝集成到 Lovrabet 主应用中。

典型需求:

  • 在 Lovrabet 订单管理系统中，开发一个"销售漏斗分析"可视化大屏
  • 为 Lovrabet 项目管理系统增加"甘特图时间线"交互页面
  • 开发一个"数据导入向导"页面，简化批量导入流程
  • 自定义"仪表盘"页面，展示企业专属的 KPI 指标

推荐方案: ✅ WebAPI (Cookie 模式) + icestark 微前端

方式 1: 使用 Lovrabet CLI 快速创建（推荐）​

使用 Lovrabet CLI 可以一键创建微前端子应用，自动配置 icestark、SDK 和 WebAPI 认证：

# 安装 CLI
npm install -g @lovrabet/cli

# 创建项目
lovrabet create my-custom-page

# 配置并拉取 SDK
lovrabet config set app <你的应用代码>
lovrabet api pull
详细教程

完整的创建和开发流程，请参考 Lovrabet CLI 快速上手

创建完成后，在项目中使用 SDK：

// 从 CLI 自动生成的 API 文件中导入
import { lovrabetClient } from "@/api/client";

export default function Dashboard() {
  const [orders, setOrders] = useState([]);

  useEffect(() => {
    // 自动继承 Lovrabet 主应用登录态
    lovrabetClient.models.orders
      .filter(
        { status: "in_progress" },
        [{ gmt_create: "desc" }] // 使用 sortList 参数排序
      )
      .then((res) => setOrders(res.tableData));
  }, []);

  return <SalesFunnelChart data={orders} />;
}

方式 2: 手动集成 icestark（高级）​

如果您需要更灵活的配置，可以手动集成 icestark。

完整示例

我们提供了一个完整的 icestark 子应用示例项目，包含完整的配置和最佳实践：

👉 sub-app-react-demo

核心代码示例:

// 子应用入口 - src/index.tsx
import ReactDOM from "react-dom";
import { isInIcestark, setLibraryName } from "@ice/stark-app";
import { createClient } from "@lovrabet/sdk";
import App from "./App";

// 初始化 SDK（自动继承 Lovrabet 登录态）
const client = createClient({
  appCode: "your-app-code",
  models: {
    orders: { tableName: "orders", datasetCode: "ds-001" },
  },
});

// icestark 挂载生命周期
export function mount(props) {
  ReactDOM.render(<App sdkClient={client} {...props} />, props.container);
}

// icestark 卸载生命周期
export function unmount(props) {
  ReactDOM.unmountComponentAtNode(props.container);
}

// 设置库名称（需要与 webpack 配置的 output.library 保持一致）
setLibraryName("lovrabetSubApp");

// 独立运行时支持（开发调试）
if (!isInIcestark()) {
  ReactDOM.render(
    <App sdkClient={client} />,
    document.getElementById("ice-container")
  );
}

Lovrabet 主应用配置:

子应用开发完成后，需要在 Lovrabet 平台添加页面配置，将子应用集成到主应用中。

配置步骤：

  1. 在 Lovrabet 平台添加源码页面

    登录 Lovrabet 平台，在应用中选择"添加页面" → "源码类型页面"，配置以下信息：

    添加源码页面

  2. 配置路由信息

    配置路由

配置项说明：

配置项说明示例
路由路径子应用在主应用中的访问路径/sales-funnel
微应用唯一标识icestark 的 appName，需与子应用 setLibraryName() 一致salesFunnelApp
basename子应用路由的 base 路径（可选）留空或填写路由前缀
资源加载方式选择 import (适用于 es module)推荐使用 ES Module 方式
资源加载列表子应用构建产物的 JS 和 CSS 文件 URLhttps://your-domain.com/dist/main.js
https://your-domain.com/dist/main.css

示例配置：

路由路径: /sales-funnel
微应用唯一标识: salesFunnelApp
资源加载方式: import (适用于 es module)
资源加载列表:
  https://your-domain.com/dist/sales-funnel/main.js
  https://your-domain.com/dist/sales-funnel/main.css

核心优势:

  • ✅ 无缝集成 - 子应用自动继承 Lovrabet 主应用登录态和权限
  • ✅ 零配置认证 - 使用 WebAPI Cookie 模式，无需管理 AccessKey
  • ✅ CLI 工具支持 - 一键创建、自动配置、快速开发
  • ✅ 独立开发调试 - 基于 icestark，子应用可独立运行

相关文档:

场景 2: 开发第三方小程序或独立应用​

业务场景:

基于 Lovrabet 生成的业务 API，开发一个独立的第三方应用（如微信小程序、企业微信应用、钉钉小程序等），拥有自己的用户体系和权限控制。

典型需求:

  • 开发一个"客户查询"微信小程序，供销售人员外出时使用
  • 开发企业微信应用，让员工在移动端审批工单
  • 开发钉钉小程序，展示实时库存数据
  • 开发独立的移动 App，提供给合作伙伴使用

推荐方案: ✅ OpenAPI (Token 模式)

// 小程序端 - pages/index/index.js
import { createClient } from "@lovrabet/sdk";

Page({
  async onLoad() {
    // 步骤 1: 从后端获取 Token（后端使用 AccessKey 生成）
    const { token, timestamp } = await wx.request({
      url: "https://your-backend.com/api/get-lovrabet-token",
      method: "POST",
      data: { userId: this.getUserId() }, // 传递小程序用户ID
    });

    // 步骤 2: 使用 Token 创建客户端
    const client = createClient({
      appCode: "your-app-code",
      token: token,
      timestamp: timestamp,
      models: {
        customers: { tableName: "customers", datasetCode: "ds-001" },
      },
    });

    // 步骤 3: 查询客户数据
    const customers = await client.models.customers.filter({
      salesperson: this.getUserName(), // 根据销售人员过滤
      pageSize: 20,
    });

    this.setData({ customers });
  },
});

后端 Token 生成接口:

// 后端 API - /api/get-lovrabet-token
import { generateOpenApiToken } from "@lovrabet/sdk";

export async function POST(request) {
  const { userId } = await request.json();

  // 1. 验证小程序用户身份
  const user = await validateWechatUser(userId);
  if (!user) {
    return Response.json({ error: "未授权" }, { status: 401 });
  }

  // 2. 生成 Lovrabet OpenAPI Token
  const { token, timestamp, expiresAt } = await generateOpenApiToken({
    appCode: process.env.LOVRABET_APP_CODE,
    datasetCode: process.env.LOVRABET_DATASET_CODE,
    accessKey: process.env.LOVRABET_ACCESS_KEY,
  });

  // 3. 返回给小程序
  return Response.json({ token, timestamp, expiresAt });
}

核心优势:

  • ✅ 独立用户体系 - 小程序用户与 Lovrabet 用户完全独立
  • ✅ 自主权限控制 - 后端可根据小程序用户角色动态生成不同权限的 Token
  • ✅ 跨平台支持 - 同一套 API 可用于微信、企业微信、钉钉、独立 App
  • ✅ 安全可控 - Token 有效期 10 分钟，后端可实现更细粒度的权限控制

适用场景: 微信小程序、企业微信、钉钉、uniapp、React Native、Flutter 等

场景 3: 服务端数据集成（BI/数据仓库）​

业务场景:

将 Lovrabet 系统中的业务数据定时同步到企业数据仓库、BI 系统或大数据平台，用于深度分析和报表生成。

典型需求:

  • 每天凌晨同步 Lovrabet 订单数据到数据仓库
  • 实时同步客户信息到企业 CRM 系统
  • 定期导出数据到 Excel 供管理层查看
  • 对接企业数据中台，实现数据统一治理

推荐方案: ✅ OpenAPI (AccessKey 模式)

// cron-job.js - 定时任务脚本
import { createClient } from "@lovrabet/sdk";
import { syncToDataWarehouse } from "./utils";

const client = createClient({
  appCode: process.env.LOVRABET_APP_CODE,
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  models: {
    orders: { tableName: "orders", datasetCode: "ds-001" },
    customers: { tableName: "customers", datasetCode: "ds-002" },
  },
});

// 每天凌晨 2 点执行
async function syncDailyData() {
  console.log("开始同步数据...");

  // 批量获取昨日订单
  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);

  let currentPage = 1;
  let totalSynced = 0;

  while (true) {
    const { tableData, paging } = await client.models.orders.filter({
      currentPage,
      pageSize: 100,
      create_date: yesterday.toISOString().split("T")[0],
    });

    // 同步到数据仓库
    await syncToDataWarehouse(tableData);
    totalSynced += tableData.length;

    if (currentPage * paging.pageSize >= paging.totalCount) break;
    currentPage++;
  }

  console.log(`同步完成，共 ${totalSynced} 条数据`);
}

核心优势:

  • ✅ 服务端运行 - 可安全使用 AccessKey，无泄露风险
  • ✅ 批量处理 - 支持大数据量的高效同步
  • ✅ 稳定可靠 - 不依赖用户登录，适合自动化任务
  • ✅ 灵活调度 - 可按需定时、实时或事件触发

场景 4: 第三方系统集成（ERP/OA/财务系统）​

业务场景:

企业已有 ERP、OA、财务系统等，需要与 Lovrabet 系统进行数据互通，实现业务流程打通。

典型需求:

  • ERP 系统需要读取 Lovrabet 的客户和订单数据
  • 财务系统需要从 Lovrabet 获取收款记录
  • OA 审批流需要调用 Lovrabet 数据进行验证
  • 电商系统需要同步 Lovrabet 的库存信息

推荐方案: ✅ OpenAPI (AccessKey 模式)

# Python ERP 系统集成示例
import requests
import hmac
import hashlib
import time

class LovrabetClient:
    def __init__(self, app_code, access_key):
        self.app_code = app_code
        self.access_key = access_key
        self.base_url = "https://runtime.lovrabet.com"

    def generate_token(self, dataset_code):
        timestamp = int(time.time() * 1000)
        params = f"accessKey={self.access_key}&appCode={self.app_code}&datasetCode={dataset_code}&timeStamp={timestamp}"
        token = hmac.new(
            b"lovrabet",
            params.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        return token, timestamp

    def get_orders(self, dataset_code):
        token, timestamp = self.generate_token(dataset_code)

        response = requests.post(
            f"{self.base_url}/openapi/data/get-list",
            headers={
                "X-Time-Stamp": str(timestamp),
                "X-App-Code": self.app_code,
                "X-Dataset-Code": dataset_code,
                "X-Token": token,
                "Content-Type": "application/json"
            },
            json={
                "appCode": self.app_code,
                "datasetCode": dataset_code,
                "paramMap": {
                    "currentPage": 1,
                    "pageSize": 50,
                    "status": "confirmed"
                }
            }
        )

        return response.json()

# 在 ERP 系统中使用
client = LovrabetClient(
    app_code="your-app-code",
    access_key="your-access-key"
)

orders = client.get_orders("ds-001")
# 将订单数据同步到 ERP 系统
erp_system.sync_orders(orders['data']['tableData'])

核心优势:

  • ✅ 跨语言支持 - Python、Java、Go、PHP 等任意后端语言
  • ✅ 标准协议 - 基于 HTTP + HMAC 签名，业界通用
  • ✅ 独立认证 - 不依赖 Lovrabet 用户登录
  • ✅ 企业级稳定 - 适合关键业务系统集成

场景 5: SSR 应用（Next.js/Nuxt.js）​

业务场景:

基于 Lovrabet 数据构建一个服务端渲染（SSR）的 Web 应用，需要在服务端和浏览器端都能访问数据。

推荐方案: ✅ 混合模式 (服务端用 AccessKey，浏览器端用 Cookie 或 Token)

// app/dashboard/page.tsx - Next.js Server Component
import { createClient } from "@lovrabet/sdk";

async function getDashboardData() {
  "use server";

  // 服务端使用 AccessKey
  const client = createClient({
    appCode: process.env.LOVRABET_APP_CODE,
    accessKey: process.env.LOVRABET_ACCESS_KEY,
    models: {
      stats: { tableName: "stats", datasetCode: "ds-001" },
    },
  });

  return await client.models.stats.filter();
}

export default async function DashboardPage() {
  const stats = await getDashboardData();

  // 服务端渲染，数据已在 HTML 中
  return <DashboardView initialData={stats} />;
}

// app/profile/page.tsx - Client Component
("use client");

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

export default function ProfilePage() {
  const [data, setData] = useState(null);

  useEffect(() => {
    // 浏览器端使用 Cookie（如果用户已登录 Lovrabet）
    const client = createClient({
      appCode: "your-app-code",
      models: {
        users: { tableName: "users", datasetCode: "ds-001" },
      },
    });

    client.models.users.getOne(userId).then(setData);
  }, []);

  return <ProfileView data={data} />;
}

核心优势:

  • ✅ SEO 友好 - 服务端渲染，搜索引擎可抓取
  • ✅ 首屏性能 - 数据在服务端获取，加载更快
  • ✅ 灵活切换 - 根据场景选择服务端或客户端获取数据

安全性对比​

WebAPI 安全机制​

优点:

  • ✅ 依赖 Lovrabet 平台的用户认证体系,成熟可靠
  • ✅ 自动继承用户权限,不会越权访问
  • ✅ 无需在前端管理密钥,避免泄露风险

局限:

  • ⚠️ 必须在可信域名下或配置正确的 CORS
  • ⚠️ 使用 Cookie 认证，应用层需要实现 CSRF 防护（如使用 CSRF Token、SameSite Cookie 等）
  • ⚠️ 仅限浏览器环境,无法用于服务端

最佳实践:

// ✅ 正确:在浏览器端使用
const client = createClient({
  appCode: "your-app-code",
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// ❌ 错误:无法在 Node.js 使用
// 因为没有浏览器 Cookie
CSRF 防护建议（应用层责任）

WebAPI 使用 Cookie 认证，CSRF 防护是您的应用的责任，不是 API 层的责任。建议：

  1. 使用 CSRF Token: 在表单中添加 CSRF Token 验证
  2. SameSite Cookie: 设置 Cookie 的 SameSite 属性
  3. 验证 Referer/Origin: 在后端验证请求来源
  4. 使用框架的 CSRF 中间件: 如 Express 的 csurf、Next.js 的内置防护等

OpenAPI 模式不受 CSRF 影响，因为它使用 Token-based 认证，不依赖浏览器自动携带的 Cookie。

OpenAPI 安全机制​

优点:

  • ✅ HMAC-SHA256 签名,业界标准,安全可靠
  • ✅ Token 有效期控制(10 分钟),降低泄露风险
  • ✅ 独立认证,不依赖用户登录状态
  • ✅ 支持应用级别的细粒度权限控制

局限:

  • ⚠️ AccessKey 如果泄露,后果严重
  • ⚠️ 需要安全存储和传输密钥
  • ⚠️ Token 有时效性,需要处理刷新逻辑

最佳实践:

// ✅ 正确:服务端使用 AccessKey
// server.js (Node.js)
const client = createClient({
  appCode: process.env.APP_CODE,
  accessKey: process.env.LOVRABET_ACCESS_KEY, // 从环境变量读取
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// ✅ 正确:浏览器使用预生成 Token
// client.js (Browser)
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());
const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// ❌ 错误:在浏览器代码中硬编码 AccessKey
const client = createClient({
  accessKey: "sk_live_xxxx", // 危险!会暴露在源代码中
});

密钥管理建议:

# .env 文件(不要提交到 Git)
LOVRABET_APP_CODE=app-c2dd52a2
LOVRABET_ACCESS_KEY=your-secret-access-key
LOVRABET_DATASET_CODE=0fefba76fe29440194841f4825df53ff

# .gitignore
.env
.env.local

Token 管理与刷新​

Token 有效期​

OpenAPI Token 有效期为 10 分钟,过期后需要重新生成。

检测 Token 过期​

import { isTokenExpiring, getTokenRemainingTime } from "@lovrabet/sdk";

// 检查是否即将过期(剩余时间 < 1分钟)
if (isTokenExpiring(timestamp)) {
  console.log("Token 即将过期,需要刷新");
}

// 获取剩余时间(毫秒)
const remaining = getTokenRemainingTime(timestamp);
console.log(`Token 剩余 ${remaining / 1000} 秒`);

自动刷新策略​

策略 1: 定时刷新

let tokenData = await fetchToken();
let client = createClient({
  appCode: "your-app-code",
  token: tokenData.token,
  timestamp: tokenData.timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// 每 8 分钟刷新一次(留 2 分钟缓冲)
setInterval(async () => {
  tokenData = await fetchToken();
  client.setToken(tokenData.token, tokenData.timestamp);
}, 8 * 60 * 1000);

策略 2: 懒刷新(请求前检查)

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

async function fetchData() {
  // 请求前检查 Token 是否即将过期
  if (isTokenExpiring(tokenData.timestamp)) {
    tokenData = await fetchToken();
    client.setToken(tokenData.token, tokenData.timestamp);
  }

  return await client.models.users.filter();
}

策略 3: 错误重试(推荐)

async function fetchDataWithRetry() {
  try {
    return await client.models.users.filter();
  } catch (error) {
    // 如果是 Token 过期错误(1003),刷新后重试
    if (error.statusCode === 1003) {
      tokenData = await fetchToken();
      client.setToken(tokenData.token, tokenData.timestamp);
      return await client.models.users.filter(); // 重试
    }
    throw error;
  }
}

性能对比​

对比项WebAPIOpenAPI
请求延迟低(直接调用)低(直接调用)
签名计算无HMAC-SHA256(~1ms)
Token 刷新无需刷新每 10 分钟刷新
并发性能高高
服务端调用不支持支持

性能建议:

  1. WebAPI - 适合高频的用户交互,无签名开销
  2. OpenAPI - 签名计算开销可忽略(<1ms),适合大批量数据同步

迁移指南​

从 WebAPI 迁移到 OpenAPI​

场景: 需要在服务端调用 API

// Before: WebAPI (仅浏览器可用)
const client = createClient({
  appCode: "your-app-code",
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// After: OpenAPI (服务端可用)
const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // 添加 AccessKey
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// 调用方式完全相同,SDK 自动适配
const users = await client.models.users.filter();

从 OpenAPI 迁移到 WebAPI​

场景: 已登录用户的浏览器端应用,希望简化认证

// Before: OpenAPI (需要管理 Token)
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());
const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// After: WebAPI (自动使用 Cookie)
const client = createClient({
  appCode: "your-app-code",
  // 不提供 accessKey 或 token,自动使用 Cookie
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

// 调用方式完全相同
const users = await client.models.users.filter();

常见问题​

Q1: 如何判断当前使用的是哪种模式?​

const client = createClient({
  /* ... */
});

// 检查是否为 OpenAPI 模式
if (client.isOpenApiMode()) {
  console.log("当前使用 OpenAPI (Token/AccessKey)");
} else {
  console.log("当前使用 WebAPI (Cookie)");
}

Q2: 可以在同一个应用中同时使用两种模式吗?​

可以!根据运行环境自动选择:

// lib/sdk-client.ts
import { createClient } from "@lovrabet/sdk";

export function getClient() {
  // 服务端:使用 OpenAPI AccessKey
  if (typeof window === "undefined") {
    return createClient({
      appCode: process.env.APP_CODE,
      accessKey: process.env.LOVRABET_ACCESS_KEY,
      models: {
        /* ... */
      },
    });
  }

  // 浏览器端:使用 WebAPI Cookie
  return createClient({
    appCode: process.env.NEXT_PUBLIC_APP_CODE,
    models: {
      /* ... */
    },
  });
}

Q3: WebAPI 是否支持 CORS?​

支持,但需要配置:

// 需要在 Lovrabet 平台配置允许的域名
// 或者将前端部署在 Lovrabet 同域下

Q4: OpenAPI 的签名算法可以自定义吗?​

不可以。签名算法固定为 HMAC-SHA256,secretKey 固定为 "lovrabet",这是为了保证安全性和兼容性。

Q5: 如果 Token 过期了会发生什么?​

try {
  const users = await client.models.users.filter();
} catch (error) {
  if (error.statusCode === 1003) {
    console.error("Token 已过期,请刷新 Token");
    // 刷新逻辑
  }
}

快速选择指南​

业务场景推荐方案核心理由
Lovrabet 微前端定制页面WebAPI (Cookie)无缝继承主应用登录态，零配置
第三方小程序/独立 AppOpenAPI (Token)独立用户体系，自主权限控制
数据同步到 BI/数仓OpenAPI (AccessKey)服务端批量处理，稳定可靠
ERP/OA/财务系统集成OpenAPI (AccessKey)跨语言支持，企业级稳定
Next.js SSR 应用混合模式服务端用 AccessKey，浏览器用 Cookie

核心原则:

  • 🎯 在 Lovrabet 内部开发 → 用 WebAPI，享受一体化体验
  • 🚀 独立应用开发 → 用 OpenAPI，自主可控
  • 🔄 系统对接集成 → 用 OpenAPI (AccessKey)，标准协议
  • 🎨 需要灵活性 → 两种模式可混合使用
推荐阅读
  • 微前端集成？向上滚动查看"场景 1: 基于 Lovrabet 开发个性化页面"
  • 小程序开发？向上滚动查看"场景 2: 开发第三方小程序或独立应用"
  • 数据集成？向上滚动查看"场景 3"和"场景 4"

相关文档​

需要帮助?​

如遇到问题:

  1. 查看 GitHub Issues
  2. 联系商务经理获取技术支持