即时API(Instant API)

Instant API 是每个 Lovrabet dataset 自动具备的数据接口层。只要 dataset 已经存在，平台就可以围绕这个 dataset 提供 9+ 个常用 API，用于列表查询、详情读取、写入、批量写入、统计、选项数据和导出。

它的关键价值不是“少写几个 CRUD 接口”，而是让页面、服务端任务、第三方系统和 Agent 都沿着同一个业务模型工作。DBAgent 会先还原业务对象和业务关系，后续 Instant API、SDK、页面和 Backend Function Hooks 才能共享同一套业务语义。

1. Instant API 解决什么问题

问题	没有 Instant API 时	使用 Instant API 后
列表页	每张表都要手写列表接口	直接调用 filter
详情页	手写按 ID 查询接口	直接调用 getOne
表单提交	手写新增、更新、删除接口	直接调用 create / update / delete
批量导入	前端循环调用 create 或自建批量接口	直接调用 batchCreate
统计看板	一开始就写 SQL 或 BFF	先用 aggregate 覆盖常见统计
下拉框	为每个选择器写 options 接口	直接调用 getSelectOptions
导出	页面筛选和导出逻辑分叉	excelExport 复用查询条件

2. 标准执行链路

页面 / 服务端 / Agent / 第三方系统
        |
        v
SDK / OpenAPI / Runtime CLI
        |
        v
Before Hook
        |
        v
Instant API
        |
        v
After Hook
        |
        v
JSON / 文件 URL / 业务结果

Before Hook 和 After Hook 不是每次都必须写。默认情况下，Instant API 可以直接使用；当业务需要统一校验、鉴权、脱敏、补字段时，再把规则放进 Hook。

3. 三种常见调用方式

调用方式	适合场景	典型入口
TypeScript SDK	Web、Node.js、SSR、小程序、Agent 运行时	client.models.orders.filter(...)
Java OpenSDK	Spring Boot、Java 服务、批任务、企业系统集成	LovrabetSDKClient
Runtime CLI	调试、自动化脚本、Agent 工具执行	lovrabet data filter --code ...
OpenAPI	第三方系统、非 SDK 语言、外部服务	AccessKey + HTTP

4. 与 Backend Function 的边界

Instant API 面向单个 dataset 的标准动作。只要业务目标能表达为“查、改、统计、导出某个 dataset”，优先用 Instant API。

当一次业务动作需要跨多个 dataset、调用外部服务、做事务编排、补偿或异步处理时，再使用 Backend Function Endpoint。Endpoint 可以在内部继续调用 Instant API，但它本身是更高一层的业务编排入口。

5. 命名约定

统一使用 Instant API。不要再把这组能力称为“标准接口”“即时 OpenAPI”或“自动 CRUD 接口”。在兼容旧文档时，可以说明旧称对应关系，但新文档和产品页都应使用 Instant API。