FAQ 与实践建议
1. 概念与调用模式
1.1 Instant API、WebAPI、OpenAPI、Client API 是一回事吗
不是一回事。
Instant API 是每个 dataset 自动具备的数据能力，例如 filter、aggregate、getOne、create。WebAPI、OpenAPI、Client API 是调用这些能力的三种入口。
| 概念 | 定位 |
|---|---|
| Instant API | dataset 的标准数据能力 |
| WebAPI | Cookie 登录态入口，路径为 /api/{appCode}/{datasetCode}/{method} |
| OpenAPI | HMAC 签名入口，路径为 /openapi/data/{method} |
| Client API | 个人身份认证入口，路径为 /client/{appCode}/{datasetCode}/{method} |
1.2 三种模式分别用于什么场景
| 模式 | 适用场景 |
|---|---|
| WebAPI | Lovrabet 生成页面、微前端子应用、同域浏览器环境 |
| OpenAPI | 第三方系统、服务端任务、Agent 网关、跨系统集成 |
| Client API | CLI、Agent、本地脚本、服务端工具以个人身份访问数据 |
本文档里的 9 个 curl 原始接口以 WebAPI 为主要说明口径。OpenAPI 的详细签名、请求体和路径规则请看 OpenAPI。
1.3 三种模式的认证方式有什么区别
| 模式 | 认证方式 | 请求头或凭证 |
|---|---|---|
| WebAPI | Cookie 会话认证 | Cookie |
| OpenAPI | HMAC-SHA256 签名 | X-Time-Stamp、X-App-Code、X-Dataset-Code、X-Token |
| Client API | 个人身份认证 | X-User-AK |
AccessKey 只能放在服务端，不要写入前端代码、公开仓库或日志。
2. 接口范围与命名口径
2.1 为什么说是 9+
当前核心文档以 9 个常用能力为主：filter、aggregate、getOne、create、batchCreate、update、delete、getSelectOptions、excelExport。写成 9+ 是为了给后续新增 dataset 标准能力留空间。
2.2 OpenAPI 是否支持全部 9 个 Instant API
不是。
WebAPI 和 Client API 覆盖 9 个核心 Instant API。OpenAPI 当前支持部分数据操作，例如 filter、aggregate、getOne、create、batchCreate、update；delete、getSelectOptions、excelExport 当前不走 OpenAPI 模式。
2.3 getList 还要不要讲
新文档主推 filter。如果旧文档或旧代码里有 getList，可以作为兼容概念提到，但不要作为新的推荐入口。
3. 调用方式与 SDK
3.1 Node.js SDK 文档应该放在哪里
Instant API 文档只说明原始接口和 SDK 方法的对应关系，不复制 SDK 的完整 Reference。Node.js / TypeScript SDK 的安装、配置、认证、模型声明、类型和错误处理请看 TypeScript SDK。
3.2 Java SDK 文档应该放在哪里
Java 服务端接入、请求对象、认证和调用示例请看 Java SDK。Instant API 文档不复制 Java SDK 的完整 Reference。
3.3 OpenAPI 详细文档应该放在哪里
OpenAPI 的认证、签名、路径、请求体和完整接口说明请看 OpenAPI。
4. 与 SQL、Endpoint、Hook 的关系
4.1 filter 能替代 SQL 吗
不能。filter 适合列表和条件查询；aggregate 适合常见统计；复杂 SQL 口径、窗口函数、多层子查询和固定报表可以使用 Custom SQL。
4.2 Instant API 和 Backend Function Endpoint 怎么选
能表达为单个 dataset 的标准动作时，优先用 Instant API。需要跨多个 dataset、调用外部服务、做事务编排或异步流程时，使用 Endpoint。
Endpoint 可以在内部继续调用 Instant API，但 Endpoint 本身是更高一层的业务编排入口。
4.3 Hook 会不会影响所有调用方
Hook 挂在 Instant API 的后端执行链路上。通过 WebAPI、Client API，以及 OpenAPI 已支持的 Instant API 发起调用时，对应的 Before Hook / After Hook 会统一生效。
需要注意两点：
- OpenAPI 暂不支持的
delete、getSelectOptions、excelExport，不存在对应的 OpenAPI 调用链路。 - Custom SQL、Endpoint 等不是某个 dataset 的同一个标准动作时，不应默认假设会触发该 dataset 的 Instant API Hook。
5. 实践建议
5.1 写操作如何降低风险
- 先确认 dataset 详情和字段。
- 自动化场景先使用 dry-run 或等价预检查。
- 删除必须显式确认。
- 业务校验放到 Before Hook。
- 生产环境尽量用软删除和审计。
5.2 下拉框为什么用 getSelectOptions
因为很多表单只是需要某个 dataset 的选项数据，不需要查完整列表，也不需要额外写一个 options 接口。原则是“谁的数据，谁提供选项”。
5.3 文档维护规则
- 新文档统一使用
Instant API。 - 数量口径统一写
9+。 - 9 个核心 API 的 curl 原始接口和 Node.js SDK 封装说明合并到
Instant API：9 个原始接口与 Node.js SDK 封装。 - SDK 细节引导到 TypeScript SDK / Java SDK 文档，不在 Instant API 文档里复制全部 SDK Reference。
- OpenAPI 细节引导到 OpenAPI 文档，不用 WebAPI 的 curl 示例推断 OpenAPI 请求体。