用途
该技能适用于 Backstage 插件需要与 Catalog 交互的场景，包括：按 ref 获取特定实体（如 Group、Component 或 User）；按过滤条件查询实体（如某团队拥有的所有 Component、某类型的所有 Group）；以编程方式注册新的目录位置、刷新实体或注销实体。该技能同时适用于前端和后端代码，两者的入口点不同，但操作本身相同。
主要能力与模式选择
前端（在前端插件组件中）
- 按 ref 获取单个实体：useApi(catalogApiRef).getEntityByRef(ref)，参考 references/fetch-by-ref.md 的 Frontend 部分。
- 按过滤条件查询实体：useApi(catalogApiRef).getEntities({ filter })，参考 references/query-entities.md 的 Frontend 部分。
- 注册 / 刷新 / 注销位置：useApi(catalogApiRef).addLocation / refreshEntity / removeLocationById，参考 references/register-entity.md 的 Frontend 部分。
后端（在后端插件或模块中）
- 按 ref 获取单个实体：通过 catalogServiceRef 调用 catalog.getEntityByRef(ref, { credentials })，参考 references/fetch-by-ref.md 的 Backend 部分。
- 按过滤条件查询实体：通过 catalogServiceRef 调用 catalog.getEntities({ filter }, { credentials })，参考 references/query-entities.md 的 Backend 部分。
- 注册 / 刷新 / 注销位置：通过 catalogServiceRef 调用 catalog.addLocation / refreshEntity / removeLocationById，参考 references/register-entity.md 的 Backend 部分。
使用方式：两种调用模式
- 独立模式（开发中途）：用户正在编辑已有插件。根据上述情况表选择正确的参考并应用。
- 脚手架生成后模式（由 creating-backstage-plugin 调用）：将模式应用到刚生成的插件。每个参考的“Post-scaffold usage”部分会指明文件名和插入点——前端模板脚手架使用前端模式，后端模板脚手架使用后端模式。
常见陷阱
- 前端代码中，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，而服务 ref 是规范接口。
- getEntityByRef 返回 Entity | undefined。始终处理 undefined 情况（实体可能已被删除，或 ref 格式错误）。
- getEntities 返回 { items: Entity[] }——需要解构或访问 .items。
- getEntities 的过滤条件在单个对象内为 AND 组合，在对象数组之间为 OR 组合。
- 前端：不要在渲染中获取数据——用 react-use 的 useAsync（挂载/依赖变化时自动获取）或 useAsyncFn（按钮触发获取）包装。不要手动为 { loading, error, data } 接线 useState——该 hook 会正确处理竞态条件和卸载清理。
- 后端：不要在每次 HTTP 请求时都无缓存地获取——对于热路径，使用 coreServices.cache 缓存不需要实时性的结果。
UI 约定
尽可能使用 @backstage/ui 进行渲染（Skeleton、Alert、Text、Flex、Button 等）。完整组件目录和样式指南参见 using-backstage-ui 技能。
适用场景与限制
该技能面向 Backstage 插件开发者，用于在前后端代码中规范地与 Catalog 交互。资料未提供具体的安装命令、版本要求、收费信息或平台限制；相关细节暂未提供。