Backstage 软件目录筛选完全指南掌握 Catalog 过滤与定制【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南围绕 Backstage 软件目录Software Catalog的筛选功能展开完整讲解目录首页提供的全部筛选维度名称、Kind、类型、Owner、Lifecycle、处理状态、命名空间等并结合仓库源码剖析其底层过滤机制与自定义方式。读完本文你将能在日常使用中快速定位目标实体也能通过app-config.yaml或前端扩展定制属于你自己的目录筛选体验。说明本文关联文档为 docs/getting-started/filter-catalog.md所有源码引用均来自当前仓库实际文件读者可随时跳转核对。目录筛选能力总览Backstage 软件目录Software Catalog是开发者门户的核心它以 YAML 描述文件catalog-info.yaml为源经过摄取Ingestion、处理Processing、缝合Stitching三个阶段把散落在代码仓库、LDAP、云平台等处的实体Entity汇聚成可查询的统一视图。而目录首页Catalog Index Page提供的筛选能力正是让这张大表在数百上千个实体中快速定位目标的入口。目录首页支持按以下维度的任意组合进行过滤名称NameKind实体种类类型TypeOwner所有者Lifecycle生命周期处理状态Processing Status命名空间Namespace标签Tag——筛选器列表中同样内置这些维度在界面上以Filter搜索框加多个下拉列表的形式呈现如下图所示。关于筛选器可用的筛选条件如何修改参见 Catalog 定制文档关于目录中显示的实体种类可参阅技术总览中软件目录系统模型一节。从源码看这些筛选器在 plugins/catalog-react/src/components/ 下各有一个独立组件实现并通过useEntityList()这一共享的实体列表上下文由 useEntityListProvider 提供统一向目录 API 发送查询。每个筛选器最终会被转换成一组目录查询过滤器catalog filters例如EntityKindFilter会生成{ kind: value }EntityTypeFilter会生成{ spec.type: ... }EntityOwnerFilter则基于relations.ownedBy关联进行匹配见 plugins/catalog-react/src/filters.ts。按名称筛选Filter by Name在目录页顶部的Filter输入框中连续输入一个或多个字母列表会实时过滤凡是名称中不包含该字符串的实体都会被排除出显示列表。从实现上看这一行为由 EntitySearchBar 组件 完成。它采用250ms 防抖useDebounce后调用updateFilters({ text: new EntityTextFilter(search) })避免每次按键都向后端发起请求。底层EntityTextFilter见 filters.ts不仅匹配metadata.name还会匹配metadata.title实体标题spec.profile.displayName如 User 的显示名spec.target/spec.targetsLocation 实体的目标地址metadata.tags标签要求完整精确匹配标签值也就是说按名称筛选实际是对名称、标题、显示名、目标地址与标签的全文模糊匹配这一点在排查我明明输对了名字却没搜到之类的疑问时非常有用——例如标签java可以完整匹配而jav前缀则不能命中标签。按 Kind 筛选Filter by Kind使用Kind下拉列表选择要展示的实体种类。目录默认支持以下 KindKind含义API服务暴露的 API 描述Component组件服务、库、网站等Group组织内的用户组Location指向其他描述文件位置的占位实体System由多个组件组成的系统Template软件模板ScaffolderUser用户从 EntityKindPicker 源码 可以看到两个实用细节默认初始筛选为componentinitialFilter component即打开目录页时默认只显示 Component 实体组件还支持allowedKinds属性限定下拉中可选的 Kind。下拉中的 Kind 列表是从目录 API 动态拉取useAllKinds()即只展示当前目录中实际存在的 Kind而不是写死的七个选项。另外Kind 选择还支持通过URL 查询参数kind初始化queryParameters.kind因此你可以直接访问类似/catalog?kindsystem的链接直达筛选结果该链接也便于分享给同事。按类型筛选Filter by TypeType下拉列表用于按实体的spec.type字段过滤。类型选项是动态的它取决于当前Kind下拉中选中的实体种类该 Kind 下你实际注册了哪些类型。例如对于Component常见的spec.type有service、website、library、documentation等而API则常见openapi、asyncapi、graphql等。底层由 EntityTypePicker 实现EntityTypeFilter会把选择转换为{ spec.type: [...] }查询条件见 filters.ts。按标签筛选Filter by Tag与 Type 相邻目录首页还内置了Tag标签筛选器EntityTagPicker按metadata.tags匹配。与文本模糊搜索不同标签筛选是精确匹配EntityTagFilter.filterEntity要求实体包含所有选中的标签AND 语义并转换为{ metadata.tags: [...] }查询见 filters.ts。这对于用标签标记环境production、团队platform-team等场景非常顺手。按 Owner 筛选Filter by OwnerOwner下拉用于按实体所有者过滤目录。它依据实体的relations.ownedBy关系来确定归属即谁拥有该实体。实现上由 EntityOwnerPicker 提供并有两个值得注意的行为支持多选multiple可同时选择多个所有者匹配满足任一所有者的实体当 Kind 筛选为user或group时Owner 筛选器会自动隐藏因为 User/Group 实体没有典型的所有者关系见源码中的提前return null逻辑下拉选项通过虚拟化列表VirtualizedListbox与滚动分页加载实体数量很大时依然流畅。Owner 筛选同样支持 URL 参数owners多选时可用逗号分隔形式拼接到地址栏。按生命周期筛选Filter by LifecycleLifecycle下拉按实体的spec.lifecycle字段过滤。常见取值有production生产、experimental实验、deprecated已弃用等由 EntityLifecyclePicker 实现EntityLifecycleFilter转换为{ spec.lifecycle: ... }查询见 filters.ts。这让你可以一键只看生产环境中的组件或排查仍处于实验阶段的系统。按处理状态筛选Filter by Processing StatusProcessing Status下拉用于只显示处理异常或有孤儿风险的实体是运维排查的利器Orphaned孤儿实体失去了所有父实体引用被打上backstage.io/orphan: true注解但仍保留在目录中详见实体生命周期文档中的 Orphaning 一节In Error错误实体在摄取或处理阶段出错例如注册的 YAML 文件被删除、内容无法解析等详见实体生命周期文档中的 Errors 一节。该筛选由 EntityProcessingStatusPicker 实现。它的价值在于实体处理错误通常不会导致实体消失而是保留旧版本并标记错误状态如果不主动筛选用户很难察觉。使用该筛选器可以快速把处理失败和即将被自动清理的孤儿实体一网打尽。按命名空间筛选Filter by NamespaceNamespace下拉按实体所属的命名空间过滤。命名空间是实体的逻辑隔离维度默认命名空间为default常用于区分环境或团队边界。该筛选由 EntityNamespacePicker 实现EntityNamespaceFilter转换为{ metadata.namespace: ... }查询见 filters.ts。内置的我的实体用户列表User List除了上述维度筛选器目录页左侧还有一个容易被忽略但使用频率极高的内置筛选——UserListPicker。它提供owned我拥有的、starred我收藏的、all全部等视图默认视图为owned。它通过 UserListPicker 实现并依赖当前登录用户的relations.ownedBy关系测试用例见 UserListPicker.test.tsx。在配置中定制筛选器app-config.yaml 扩展对于使用新前端系统Backstage 新应用默认启用的用户目录页的筛选器可以通过app-config.yaml的app.extensions进行声明式定制无需编写 React 代码。设置 Kind 筛选器的初始值例如默认显示domainapp: extensions: - catalog-filter:catalog/kind: config: initialFilter: domain将用户列表的初始筛选从 owned 改为 allapp: extensions: - catalog-filter:catalog/list: config: initialFilter: all禁用内置的默认筛选器将其配置为false即可app: extensions: - catalog-filter:catalog/lifecycle: false - catalog-filter:catalog/tag: false - catalog-filter:catalog/processing-status: false从配置键可以看到每个内置筛选器对应一个catalog-filter:catalog/name扩展实例kind、type、owner、lifecycle、tag、namespace、processing-status、list。除 kind 与 list 外多数筛选器同样支持通过initialFilter等配置项设定初始状态。完整的扩展配置说明参见 Catalog 定制文档。进阶在代码中创建自定义筛选器当内置维度不够用时可以用CatalogFilterBlueprint编写自定义筛选器并注册为前端模块同样针对新前端系统。// packages/app/src/catalog/SecurityTierFilter.tsx import { CatalogFilterBlueprint } from backstage/plugin-catalog-react/alpha; export const securityTierFilter CatalogFilterBlueprint.make({ name: security-tier, params: { loader: async () { const { EntitySecurityTierPicker } await import( ./EntitySecurityTierPicker ); return EntitySecurityTierPicker /; }, }, });// packages/app/src/catalog/catalogCustomizations.tsx import { createFrontendModule } from backstage/frontend-plugin-api; import { securityTierFilter } from ./SecurityTierFilter; export default createFrontendModule({ pluginId: catalog, extensions: [securityTierFilter], });// packages/app/src/App.tsx import { createApp } from backstage/frontend-defaults; import catalogCustomizations from ./catalog/catalogCustomizations; const app createApp({ features: [catalogCustomizations], }); export default app.createRoot();如果你的应用仍在使用旧前端系统catalog-customization--old.md提供了对应的旧版定制指南详见 Catalog 定制文档旧前端系统版。进阶使用实体谓词查询Entity Predicate Queries若想对哪些实体显示/不显示做更精细的规则控制例如控制实体页面上某个扩展的适用范围目录还提供了一套实体谓词查询Entity Predicate Queries语法一种受 MongoDB 查询语法启发、以 JSON/YAML 表达的迷你查询语言支持逻辑运算符$all、$any、$not与值运算符$exists、$in、$contains。基础形式——键为实体字段的完整点分路径值为大小写不敏感的匹配目标多个键之间为 AND 关系。以下匹配所有spec.type为service的 Componentfilter: kind: component spec.type: service逻辑运算符——$all全部成立空数组恒为 true、$any任一成立空数组恒为 false、$not取反filter: $all: - kind: component - $not: spec.type: servicefilter: $any: - kind: component - metadata.annotations.github.com/project-slug: { $exists: true }值运算符——$exists字段是否存在、$in值属于给定数组大小写不敏感、$contains数组字段中至少一个元素整体匹配给定表达式filter: kind: $in: [component, api]filter: relations: $contains: type: ownedBy targetRef: $in: [group:default/admins, group:default/viewers]实体谓词查询常用于实体页扩展的filter配置以决定某个扩展在哪些实体上生效。完整运算符说明与更多示例见 Catalog 定制文档中的 Entity predicate queries 一节。底层原理筛选条件如何抵达后端理解目录筛选的完整链路能帮助你更好地排查问题前端收集每个 Picker 组件通过useEntityList()调用updateFilters将自身状态写入EntityListProvider管理的共享过滤器集合翻译成查询各筛选器类EntityKindFilter、EntityTypeFilter、EntityOwnerFilter等位于 plugins/catalog-react/src/filters.ts实现getCatalogFilters()把前端筛选翻译成{ spec.type: ... }、{ relations.ownedBy: [...] }、{ metadata.tags: [...] }等目录 API 查询参数请求目录 APIEntityListProvider汇总全部筛选条件后调用catalogApi.queryEntities()或旧版getEntities()向后端发起查询后端过滤目录后端根据查询参数在数据库中过滤其索引由缝合阶段的搜索表支撑详见实体生命周期文档并返回符合全部条件的实体分页结果。因此多个筛选条件之间是 AND 关系——只有同时满足所有维度条件的实体才会出现在列表中。这也是筛选组合能快速收窄结果的原因例如KindComponent Typeservice Lifecycleproduction Owner某团队 名称含checkout即可瞬间锁定生产环境中的支付服务。延伸阅读Catalog 定制筛选器与目录页扩展——定制、禁用、新增筛选器的完整指南含目录导出、分页、实体页分组等软件目录系统模型——目录中实体种类的技术描述实体的生命周期——处理状态孤儿、错误背后的完整机制目录描述文件格式——catalog-info.yaml中spec.type、spec.lifecycle、metadata.tags等字段的定义目录筛选器组件源码——EntityKindPicker、EntityTypePicker、EntityOwnerPicker、EntityLifecyclePicker、EntityNamespacePicker、EntityProcessingStatusPicker、EntityTagPicker、UserListPicker、EntitySearchBar的具体实现筛选器类定义——每种筛选器到目录 API 查询参数的翻译逻辑【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考