Backstage 软件目录筛选完全指南:掌握 Catalog 过滤与定制
Backstage 软件目录筛选完全指南:掌握 Catalog 过滤与定制
本指南围绕 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)提供的筛选能力,正是让这张大表在数百上千个实体中快速定位目标的入口。
目录首页支持按以下维度的任意组合进行过滤:
- 名称(Name)
- Kind(实体种类)
- 类型(Type)
- Owner(所有者)
- 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.targets(Location 实体的目标地址)metadata.tags(标签,要求完整精确匹配标签值)
也就是说,"按名称筛选"实际是对名称、标题、显示名、目标地址与标签的全文模糊匹配,这一点在排查"我明明输对了名字却没搜到"之类的疑问时非常有用——例如标签 java 可以完整匹配,而 jav 前缀则不能命中标签。
按 Kind 筛选(Filter by Kind)
使用 Kind 下拉列表选择要展示的实体种类。目录默认支持以下 Kind:
| Kind | 含义 |
|---|---|
| API | 服务暴露的 API 描述 |
| Component | 组件(服务、库、网站等) |
| Group | 组织内的用户组 |
| Location | 指向其他描述文件位置的占位实体 |
| System | 由多个组件组成的系统 |
| Template | 软件模板(Scaffolder) |
| User | 用户 |
从 EntityKindPicker 源码 可以看到两个实用细节:
- 默认初始筛选为
component(initialFilter = 'component'),即打开目录页时默认只显示 Component 实体;组件还支持allowedKinds属性限定下拉中可选的 Kind。 - 下拉中的 Kind 列表是从目录 API 动态拉取(
useAllKinds()),即只展示当前目录中实际存在的 Kind,而不是写死的七个选项。
另外,Kind 选择还支持通过 URL 查询参数 kind 初始化(queryParameters.kind),因此你可以直接访问类似 /catalog?kind=system 的链接直达筛选结果,该链接也便于分享给同事。
按类型筛选(Filter by Type)
Type 下拉列表用于按实体的 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 Owner)
Owner 下拉用于按实体所有者过滤目录。它依据实体的 relations.ownedBy 关系来确定归属,即谁拥有该实体。实现上由 EntityOwnerPicker 提供,并有两个值得注意的行为:
- 支持多选(
multiple),可同时选择多个所有者,匹配满足任一所有者的实体; - 当 Kind 筛选为
user或group时,Owner 筛选器会自动隐藏(因为 User/Group 实体没有典型的所有者关系,见源码中的提前return null逻辑); - 下拉选项通过虚拟化列表(
VirtualizedListbox)与滚动分页加载,实体数量很大时依然流畅。
Owner 筛选同样支持 URL 参数 owners,多选时可用逗号分隔形式拼接到地址栏。
按生命周期筛选(Filter by Lifecycle)
Lifecycle 下拉按实体的 spec.lifecycle 字段过滤。常见取值有 production(生产)、experimental(实验)、deprecated(已弃用)等,由 EntityLifecyclePicker 实现,EntityLifecycleFilter 转换为 { 'spec.lifecycle': ... } 查询(见 filters.ts)。这让你可以一键只看"生产环境中的组件",或排查仍处于实验阶段的系统。
按处理状态筛选(Filter by Processing Status)
Processing Status 下拉用于只显示处理异常或有孤儿风险的实体,是运维排查的利器:
- Orphaned(孤儿):实体失去了所有父实体引用,被打上
backstage.io/orphan: 'true'注解,但仍保留在目录中(详见实体生命周期文档中的 Orphaning 一节); - In Error(错误):实体在摄取或处理阶段出错,例如注册的 YAML 文件被删除、内容无法解析等(详见实体生命周期文档中的 Errors 一节)。
该筛选由 EntityProcessingStatusPicker 实现。它的价值在于:实体处理错误通常不会导致实体消失,而是保留旧版本并标记错误状态,如果不主动筛选,用户很难察觉。使用该筛选器可以快速把"处理失败"和"即将被自动清理的孤儿"实体一网打尽。
按命名空间筛选(Filter by Namespace)
Namespace 下拉按实体所属的命名空间过滤。命名空间是实体的逻辑隔离维度(默认命名空间为 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 筛选器的初始值(例如默认显示 domain):
app:
extensions:
- catalog-filter:catalog/kind:
config:
initialFilter: domain
将用户列表的初始筛选从 "owned" 改为 "all":
app:
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 的 Component:
filter:
kind: component
spec.type: service
逻辑运算符——$all(全部成立,空数组恒为 true)、$any(任一成立,空数组恒为 false)、$not(取反):
filter:
$all:
- kind: component
- $not:
spec.type: service
filter:
$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 查询参数; - 请求目录 API:
EntityListProvider汇总全部筛选条件后调用catalogApi.queryEntities()(或旧版getEntities())向后端发起查询; - 后端过滤:目录后端根据查询参数在数据库中过滤(其索引由缝合阶段的搜索表支撑,详见实体生命周期文档),并返回符合全部条件的实体分页结果。
因此,多个筛选条件之间是 AND 关系——只有同时满足所有维度条件的实体才会出现在列表中。这也是"筛选组合"能快速收窄结果的原因:例如"Kind=Component + Type=service + Lifecycle=production + Owner=某团队 + 名称含 checkout"即可瞬间锁定生产环境中的支付服务。
延伸阅读
- Catalog 定制:筛选器与目录页扩展——定制、禁用、新增筛选器的完整指南(含目录导出、分页、实体页分组等)
- 软件目录系统模型——目录中实体种类的技术描述
- 实体的生命周期——处理状态(孤儿、错误)背后的完整机制
- 目录描述文件格式——
catalog-info.yaml中spec.type、spec.lifecycle、metadata.tags等字段的定义 - 目录筛选器组件源码——
EntityKindPicker、EntityTypePicker、EntityOwnerPicker、EntityLifecyclePicker、EntityNamespacePicker、EntityProcessingStatusPicker、EntityTagPicker、UserListPicker、EntitySearchBar的具体实现 - 筛选器类定义——每种筛选器到目录 API 查询参数的翻译逻辑

