API 与数据集：拉配置、看清数据

这一节解决三类问题：本地 api.ts 怎么来、平台上到底有哪些数据集、字段是什么、能调哪些操作，以及少量数据集元数据怎么安全维护。前提：已完成登录，且当前 App Code、环境正确（见“配置：应用、环境、多应用”）。

为什么要先 `api pull`

前端里用到的数据集别名、请求封装，通常来自项目里的 **API 目录 **（默认 ./src/api/，可在配置里改 apiDir）。和平台不一致时，会出现「代码里写的别名对不上」「拉列表报错」之类问题。习惯上在以下时机拉一次：

刚接入项目、project init 之后
平台上增删改过数据集或模型
切换了 appcode / env

命令：

rabetbase api pull

指定输出目录：

rabetbase api pull --output ./src/api

拉下来之后，本地会有一份和当前 App 对齐的模型列表，后面的 codegen、dataset --alias 等都会用到这里的别名。

列出当前应用下所有模型（数据集）

有时你想在终端快速看一眼，不必打开文件：

rabetbase api list

多应用模式下会按配置逐个 App 列出（具体输出格式可用 --format json / pretty / compress）。

按数据集做只读探查

列出数据集（支持服务端过滤，不必全量硬拉）：

rabetbase dataset list
rabetbase dataset list --name 订单
rabetbase dataset list --code <32位code>
rabetbase dataset list --source DB_TABLE
rabetbase dataset list --source METADATA

默认情况下，dataset list 返回当前应用下的 DO V2 数据集，包括 DB_TABLE 和 METADATA。列表结果是轻量摘要：会包含 id、name、code、source，以及列表接口提供的表名、主键和字段摘要。完整字段、操作和关联页仍以 dataset detail 为准。

按来源筛选时，用 --source：

目标	命令
只看数据库表数据集	`rabetbase dataset list --source DB_TABLE`
只看元数据数据集	`rabetbase dataset list --source METADATA`

写自定义 SQL 或做 SQL schema 校验时，请选择 DB_TABLE 数据集。METADATA 数据集没有物理表上下文，适合页面生成、关系检查等平台元数据场景；如果需求是查看真实业务行数据，应转到运行态 lovrabet data filter|getOne。

看某一个数据集的完整信息（字段、元数据等）：

rabetbase dataset detail --code <32位code>

若已经 api pull 过，可以用别名代替长 code：

rabetbase dataset detail --alias order

只看这个数据集有哪些操作（filter、getOne、create 等）：

rabetbase dataset operations --alias order
rabetbase dataset operations --alias order --operation filter

带 --operation 时可以看到该操作的参数定义，写 BFF 或 codegen 时很有用。

摸清表与表之间的关系

要做跨表查询、写复杂 SQL、或让 AI 帮你写脚本时，先搞清楚「谁连谁」会省很多返工：

rabetbase dataset links

可按数据库筛：

rabetbase dataset links --db 

返回里会有字段、主外键、数据集之间的关联类型等。需要原始响应可加 --verbose。

受控维护数据集元数据

下面这些命令会修改平台数据集元数据，建议统一先跑 --dry-run，确认 before / after 和目标 selector 后再执行。

安全改名：`dataset rename`

# 只预览
rabetbase dataset rename --code <datasetCode> --name "新名称" --expect-name "当前名称" --dry-run

# 确认后执行
rabetbase dataset rename --code <datasetCode> --name "新名称" --expect-name "当前名称"

--expect-name 是当前名称校验，实际名称不匹配时会直接中止，避免别人刚改过名称时继续覆盖。

修改字段展示属性：`dataset field-update`

rabetbase dataset field-update \
  --code <datasetCode> \
  --field customerName \
  --patch-json '{"displayName":"客户名称","required":true}' \
  --expect-json '{"displayName":"客户姓名"}' \
  --dry-run

字段补丁只允许修改白名单属性：doType、displayName、description、options、required、datetimeFormat、defaultAggregation、chartRole。id、name、dbFieldName、tableName、pkField 等结构性字段禁止通过这个命令改。

修改 dataset 顶层 extend：`dataset extend-update`

rabetbase dataset extend-update \
  --code <datasetCode> \
  --patch-json '{"businessGroup":"finance"}' \
  --expect-json '{"businessGroup":"sales"}' \
  --dry-run

当前只开放 businessGroup，用于受控维护业务分组；其他 extend 字段不要通过 CLI 临时绕过。

删除数据集元数据：`dataset delete`

# 按 code 预览
rabetbase dataset delete --code <datasetCode> --dry-run

# 按数据库连接批量预览，并锁定预期数量
rabetbase dataset delete --dbid <dbId> --expected-count 3 --dry-run

# 真实删除：必须确认高危操作，并额外传 --confirm
rabetbase dataset delete --code <datasetCode> --confirm --yes

dataset delete 只删除平台数据集元数据和相关页面 / 菜单记录，不删除物理数据库或表。它属于 high-risk-write，非交互环境需要 --yes，真实删除还必须显式传 --confirm。

生成面向文档的 API 说明（可选）

如果要把当前数据集的接口说明导出成文档（默认目录与选项以 rabetbase api doc --help 为准）：

rabetbase api doc
rabetbase api doc --datasetcode ds1,ds2

适合给同事或留档，和日常写业务代码不冲突。

小结

api pull：让本地 API 配置与平台一致。
api list：终端里扫一眼模型列表。
dataset list / detail / operations：从粗到细看单个数据集；需要限定来源时用 --source DB_TABLE 或 --source METADATA。
dataset links：看库表与数据集关联，写 SQL / BFF 前先跑一遍很值。
dataset rename / field-update / extend-update / delete：只做受控的数据集元数据维护，先 dry-run，再执行。

下一步：要写平台托管的自定义 SQL，读自定义 SQL：从写到执行。

为什么要先 api pull​

列出当前应用下所有模型（数据集）​

按数据集做只读探查​

摸清表与表之间的关系​

受控维护数据集元数据​

安全改名：dataset rename​

修改字段展示属性：dataset field-update​

修改 dataset 顶层 extend：dataset extend-update​

删除数据集元数据：dataset delete​

生成面向文档的 API 说明（可选）​

小结​