NocoBase `nb api resource destroy` 命令详解：从主键到条件过滤的精准删除-港品优选

NocoBase`nb api resource destroy`命令详解：从主键到条件过滤的精准删除

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

nb api resource destroy是 NocoBase CLI 中用于删除任意资源（数据表）记录的通用删除命令。它既支持通过主键值（--filter-by-tk）精确删除单条记录，也支持通过 JSON 过滤条件（--filter）批量删除符合条件的记录，并且天然兼容关联资源（如posts.comments）和多数据源场景。读完本文，你将掌握该命令的全部参数语义、两种定位方式的取舍、关联资源删除的用法，以及它底层的 HTTP 请求实现原理。

命令概览与适用场景

在 NocoBase 的 nb api resource 命令家族中，destroy承担的是 CRUD 中的Delete语义。它面向任何注册到 NocoBase 的资源，包括：

普通资源，例如users、orders；
关联资源，例如posts.comments（需配合--source-id指定源记录）；
非main数据源中的资源（通过--data-source切换）。

它适用于运维脚本、数据清理、测试数据准备以及 AI Agent 自动化操作等场景，无需编写额外代码即可直接对 API 层发起删除请求。

用法与参数说明

基本用法

nb api resource destroy --resource <resource> [flags]

--resource为必填项，其余参数均可选。命令定义的源码位于 commands/api/resource/destroy.ts，其中 flags 全部来自 lib/resource-command.ts 中导出的destroyFlags。

定位记录的参数

参数	类型	说明
`--resource`	string	资源名称，必填，例如`users`、`orders`、`posts.comments`
`--data-source`	string	数据源 key，默认`main`
`--source-id`	string	关联资源的源记录 ID（如删除`posts.comments`时指定所属`posts`记录的 ID）
`--filter-by-tk`	string	主键值（primary key）。复合主键或多个 key 时可以传 JSON 数组
`--filter`	string	JSON 对象形式的过滤条件，用于按字段值批量定位记录

其中--resource、--data-source、--source-id属于所有 resource 子命令共享的基础参数（resourceBaseFlags/resourceAssociationFlags），而--filter-by-tk与--filter是 destroy 专属的定位参数。

两种定位方式的取舍

--filter-by-tk：按主键精准删除。适用于删除单条明确记录，语义与get的--filter-by-tk一致。当目标表是复合主键时，可传 JSON 数组，例如--filter-by-tk '[1001,2026]'。
--filter：按条件批量删除。适用于"删除所有符合某条件的记录"，例如删除所有status为archived的帖子。该值必须是合法的 JSON 对象，且不能是数组或标量。

在 lib/resource-command.ts 的buildDestroyArgs（L383-L393）中可以看到两者的解析逻辑：

--filter-by-tk走parseFlexibleValue：当值以[、{、null、true、false开头时按 JSON 解析，否则按普通字符串/数字处理，因此既支持1这样的标量，也支持[1001,2026]这样的 JSON 数组；
--filter走parseObjectFlag：必须解析为 JSON 对象，否则直接报错--filter must be a JSON object。

两个参数都未指定时，命令仍会发出请求（等价于无定位条件的删除动作），实际删除范围取决于服务端资源定义，因此建议显式传入至少一种定位方式。

通用连接参数

destroy同时支持 nb api resource 的全部通用参数：

参数	说明
`--api-base-url`	NocoBase API 地址，例如`http://localhost:13000/api`
`--verbose`	显示详细进度输出
`--env`,`-e`	环境名称
`--yes`,`-y`	当显式`--env`指向的 env 与当前 env 不一致时，跳过交互确认
`--role`	角色覆盖，作为`X-Role`请求头发送
`--token`,`-t`	API key 覆盖
`--json-output`,`-j`/`--no-json-output`	是否输出原始 JSON，默认开启

需要特别留意--env的行为：只有在显式传入--env时，CLI 才会检查其与当前 env 是否一致。如果显式指定了不同的 env，交互终端会先确认；在非交互终端或 AI Agent 场景下，需要自行显式追加--yes，或先执行nb env use <name>再重试。该逻辑实现在runResourceCommand中的ensureCrossEnvConfirmed（lib/resource-command.ts）。

完整示例

# 按主键删除 users 资源中 id 为 1 的记录 nb api resource destroy --resource users --filter-by-tk 1 # 按条件删除 posts 资源中所有 status 为 archived 的记录 nb api resource destroy --resource posts --filter '{"status":"archived"}' # 删除关联资源：posts 下 id 为 1 的评论中主键为 5 的记录 nb api resource destroy --resource posts.comments --source-id 1 --filter-by-tk 5 # 复合主键：以 JSON 数组形式传入多个 key nb api resource destroy --resource order_items --filter-by-tk '[1001,2026]' # 指定非 main 数据源并跳过跨环境确认（非交互场景） nb api resource destroy --resource legacy_orders --data-source legacy --filter '{"state":"draft"}' --env prod --yes

命令执行成功后，默认以美化后的 JSON 打印服务端响应（即--json-output默认开启）；使用--no-json-output时则只输出HTTP <status>状态行。若请求失败（ok为 false），CLI 会直接报错并携带状态码与响应体，便于定位问题（见 lib/resource-command.ts 的printResponse实现）。

底层实现：命令如何转化为 HTTP 请求

从源码结构看，destroy的完整调用链为：

commands/api/resource/destroy.ts 解析 flags 并调用runResourceCommand；
runResourceCommand先做跨环境确认，再通过executeResourceRequest发起请求；
lib/resource-request.ts 的executeResourceRequest将参数组装为一次POST请求（method: 'POST'），请求路径形如/<resource>:destroy（关联资源则拼接--source-id对应的源记录段）。

几个关键实现细节：

请求方法统一为 POST：与 NocoBase resourcer 的约定一致，destroy动作通过POST /api/<resource>:destroy触发（参见 lib/resource-request.ts）；
--filter-by-tk走查询串、--filter走请求体：定位参数在buildActionQuery/buildActionPayload中分别被组装到 query 和 body，符合 NocoBase API 对filterByTk与filter参数的区分；
多数据源通过请求头切换：当--data-source指定且不等于main时，请求会携带x-data-source头（lib/resource-request.ts），从而删除非默认数据源中的记录；
角色与鉴权：--role与--token分别对应X-Role请求头与 API key 覆盖，用于在删除时模拟特定角色或使用独立凭证。

这意味着nb api resource destroy本质上是对 NocoBase 标准 HTTP API 的一层 CLI 封装：理解它的参数，也就理解了对应 API 端点的调用方式，方便在脚本或自定义客户端中复现同样的删除操作。

注意事项与最佳实践

批量删除前先确认范围：--filter会删除所有匹配记录，属于不可逆操作。建议先用nb api resource list --resource <resource> --filter '<同一条件>'（见 list）预览命中记录，再执行删除。
复合主键必须用 JSON 数组：当目标表存在复合主键时，--filter-by-tk应传入 JSON 数组形式，例如'[1001,2026]'；普通主键直接传标量即可。
关联资源必须配合--source-id：删除posts.comments这类关联资源时，缺少--source-id将无法正确定位到源记录下的目标集合。
非交互环境记得--yes：CI 或 AI Agent 中若通过--env切换了环境，务必显式追加--yes跳过确认，否则命令会中止。
利用--verbose排查：请求异常时加--verbose可输出详细进度，结合失败响应中的状态码与 body 快速定位问题。

企业官网建设流程全解析