using-backstage-catalog

Backstage 目录模式

何时使用此技能

• 插件需要通过引用（例如 Group、Component 或 User）获取特定实体
• 插件需要使用筛选条件查询实体（例如某个团队拥有的所有 Component、某种类型的所有 Group）
• 插件需要以编程方式注册新的目录位置、刷新实体或取消注册实体
• 前端和后端代码都适用；入口点各不相同，但操作相同

选择合适的模式

前端（在前端插件组件中）

情况	模式	参考
通过引用获取一个实体	useApi(catalogApiRef).getEntityByRef(ref)	references/fetch-by-ref.md（前端部分）
使用筛选条件查询实体	useApi(catalogApiRef).getEntities({ filter })	references/query-entities.md（前端部分）
注册 / 刷新 / 取消注册一个位置	useApi(catalogApiRef).addLocation / refreshEntity / removeLocationById	references/register-entity.md（前端部分）

后端（在后端插件或模块中）

情况	模式	参考
通过引用获取一个实体	通过 catalogServiceRef 调用 catalog.getEntityByRef(ref, { credentials })	references/fetch-by-ref.md（后端部分）
使用筛选条件查询实体	通过 catalogServiceRef 调用 catalog.getEntities({ filter }, { credentials })	references/query-entities.md（后端部分）
注册 / 刷新 / 取消注册一个位置	通过 catalogServiceRef 调用 catalog.addLocation / refreshEntity / removeLocationById	references/register-entity.md（后端部分）

两种调用模式

• 独立模式（开发过程中）：用户正在编辑现有插件。根据上方情况表选择合适的参考并应用。
• 脚手架完成后（由 creating-backstage-plugin 调用）：将模式应用于刚生成脚手架的插件。每个参考中的“脚手架完成后的用法”部分会指出文件和插入位置——frontend-template 脚手架使用前端模式，backend-template 脚手架使用后端模式。

常见注意事项

• 在前端代码中，catalogApiRef 来自 @backstage/plugin-catalog-react，而不是 @backstage/catalog-client。后者用于后端。
• 在 NFS 插件中，useApi 本身来自 @backstage/frontend-plugin-api；catalogApiRef 则是特定于插件的，仍来自 @backstage/plugin-catalog-react。
• 在后端代码中，依赖 @backstage/plugin-catalog-node 中的 catalogServiceRef——它封装了已完成身份验证和服务发现配置的目录客户端，并直接接收 BackstageCredentials。方法接收 { credentials }（一个 BackstageCredentials 对象），而不是 { token }（一个字符串）。对于传入的 HTTP 请求，通过 httpAuth.credentials(req) 获取凭据。对于服务间任务（定时任务、初始化时获取数据），使用 auth.getOwnServiceCredentials()。不要手动创建 new CatalogClient(...)——它是底层 API，而服务引用才是规范的使用接口。
• getEntityByRef 返回 Entity | undefined。始终处理值为 undefined 的情况（实体可能已被删除，或引用格式错误）。
• getEntities 返回 { items: Entity[] }——解构或访问 .items。
• getEntities 的筛选条件在同一对象内按 AND 组合，在对象数组中按 OR 组合。
• 前端：不要在渲染期间获取数据——使用 react-use 中的 useAsync（在挂载或依赖项更改时自动获取）或 useAsyncFn（由按钮触发获取）。不要手动使用 useState 管理 { loading, error, data }——该 Hook 能正确处理竞态条件和卸载清理。
• 后端：不要在每个 HTTP 请求中都获取数据而不使用缓存——对于热点路径，使用 coreServices.cache 缓存无需实时更新的结果。

UI 约定

尽可能使用 @backstage/ui 进行渲染（Skeleton、Alert、Text、Flex、Button，等等）。完整的组件目录和样式指南请参阅 using-backstage-ui 技能。