Backstage 软件目录自定义完全指南:从 Catalog 索引页配置到实体谓词过滤

原创2026-09-09 19:38:491,684 阅读
文章标签:开发者门户前端后端插件系统代码生成文档研发协作云原生

Backstage 软件目录自定义完全指南:从 Catalog 索引页配置到实体谓词过滤

导读

软件目录(Software Catalog)是 Backstage 开发者门户的核心能力,而新版前端系统(new frontend system,新 Backstage 应用的默认前端系统)让目录具备了前所未有的可配置性。本指南以官方文档 catalog-customization.md 为主线,系统讲解如何通过 app-config.yaml 扩展配置目录索引页(分页、导出、内置过滤器)、如何用扩展蓝图(Blueprint)编写自定义过滤器与自定义目录页、如何理解并运用实体谓词(entity predicate)查询语法,以及如何定制实体详情页的分组、图标、内容排序和上下文菜单。读完本文,你将掌握从配置到源码的完整定制路径,并能够直接落地到自己的 Backstage 应用中。

如果你的应用仍在使用旧前端系统,请阅读旧版指南 catalog-customization--old.md。

一、目录索引页(Catalog index page)的扩展配置

目录索引页(即 /catalog 页面)在新前端系统中完全通过 app-config.yaml 的 app.extensions 字段配置。扩展配置的入口是 page:catalog,其底层实现位于 plugins/catalog/src/alpha/pages.tsx 的 catalogPage 扩展。

1.1 启用分页

最简单的分页配置只需一行布尔值:

app:
  extensions:
    - page:catalog:
        config:
          pagination: true

分页还支持更多选项:

app:
  extensions:
    - page:catalog:
        config:
          pagination:
            mode: offset
            limit: 20

从源码看,pagination 的 configSchema 支持 boolean 或对象两种形态,对象形态包含 mode('cursor' | 'offset')、可选的 limit 与 offset,默认值为 true(见 pages.tsx)。cursor 模式适合大体量目录的游标翻页,offset 模式则与传统页码分页语义一致。

1.2 配置 Catalog 数据导出(Catalog Export)

目录导出功能可以让用户在目录索引页一键把当前过滤条件下的实体以 CSV 或 JSON 格式导出,并弹出一个对话框让用户选择导出格式和包含的列。

基础配置:在 page:catalog 下开启 exportSettings:

app:
  extensions:
    - page:catalog:
        config:
          exportSettings:
            enabled: true
            # 可选:隐藏内置的 CSV 和 JSON 格式,只保留你自己提供的导出器
            disableBuiltinExporters: false

开启后,目录索引页会出现 "Export selection" 按钮,用户可将当前过滤结果按 CSV 或 JSON 格式导出。源码中 exportSettings 的 configSchema 定义了两个字段:enabled(显示导出按钮)与 disableBuiltinExporters(隐藏内置格式,仅用于只想提供自定义导出器时),见 pages.tsx。

进阶配置(自定义导出格式):当需要 XML、YAML 等自定义格式时,可通过 CatalogExportConfigBlueprint 创建前端模块。该 Blueprint 在源码中定义于 pages.tsx,其 kind 为 catalog-export-config,挂载到 page:catalog 的 exportConfig 输入上。

import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { CatalogExportConfigBlueprint } from '@backstage/plugin-catalog/alpha';
import type { CatalogExporter } from '@backstage/plugin-catalog';
import { catalogApiRef } from '@backstage/plugin-catalog-react';

// 用流式异步生成器定义自定义导出格式
const yamlExporter: CatalogExporter = ({ apis, columns, streamRequest }) => {
  const catalogApi = apis.get(catalogApiRef);

  // 返回一个逐块产出 YAML 的异步生成器
  async function* generateYaml() {
    for await (const page of catalogApi.streamEntities(streamRequest)) {
      for (const entity of page) {
        // 将每个实体序列化为 YAML 并立即产出
        yield serializeEntityToYaml(entity, columns);
        yield '---\n'; // YAML 文档分隔符
      }
    }
  }

  return {
    generator: generateYaml(),
    contentType: 'application/x-yaml',
  };
};

// 使用 Blueprint 创建扩展
const catalogExportExtension = CatalogExportConfigBlueprint.make({
  params: {
    exporters: {
      yaml: { exporter: yamlExporter, label: 'YAML' },
    },
    columns: [{ entityFilterKey: 'metadata.name', title: 'Name' }],
    onSuccess: () => {
      console.log('Export successful!');
    },
    onError: ({ error }) => {
      console.error('Export failed:', error);
    },
  },
});

// 创建提供该扩展的模块
export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [catalogExportExtension],
});

然后在应用的 features 中注册该模块:

import catalogExportExtension from './catalogExportExtension';

const app = createApp({
  features: [
    // ... other features
    catalogExportExtension,
  ],
});

CatalogExportConfigBlueprint 支持的属性如下:

  • exporters:自定义导出格式的映射表(如 XML、YAML),每项使用 CatalogExporterConfig 结构,包含 exporter 函数与可选的 label。导出器基于 catalogApi.streamEntities 流式拉取实体,适合大数据量场景;
  • columns:导出包含的自定义列。每列通过实体字段路径(entityFilterKey)和可选显示 title 指定。若未提供,默认列为 Name、Type、Owner、Description;
  • onSuccess:导出成功后的回调函数;
  • onError:导出失败后的回调,接收 { error: Error }。

从源码可以看出,页面加载时会合并所有挂载到 exportConfig 输入的扩展:exporters 会逐项合并,而 columns、onSuccess、onError 仅当未设置时才被填充(pages.tsx)。只有当 exportSettings.enabled 为 true 时,合并结果才会传给 NfsDefaultCatalogPage。

1.3 内置目录过滤器(Catalog filters)

目录索引页内置了一组默认过滤器:kind(实体类型)、type、owner(所有者)、lifecycle(生命周期)、tag(标签)、namespace(命名空间)、processing status(处理状态)。它们都可以通过 catalog-filter 扩展配置。例如设置初始 kind 过滤器为 domain:

app:
  extensions:
    - catalog-filter:catalog/kind:
        config:
          initialFilter: domain

将初始列表过滤器从默认的 "owned"(我拥有的)改为 "all"(全部):

app:
  extensions:
    - catalog-filter:catalog/list:
        config:
          initialFilter: all

1.4 自定义过滤器(Custom filters)

自定义过滤器使用 @backstage/plugin-catalog-react/alpha 中的 CatalogFilterBlueprint。该 Blueprint 的源码位于 plugins/catalog-react/src/alpha/blueprints/CatalogFilterBlueprint.ts,其 kind 为 catalog-filter,自动挂载到 page:catalog 的 filters 输入,并使用 ExtensionBoundary.lazy 对 loader 返回的 React 元素做懒加载。

以添加一个"安全等级(security tier)"过滤器为例:

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 />;
    },
  },
});

将其安装为前端模块:

import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { securityTierFilter } from './SecurityTierFilter';

export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [securityTierFilter],
});

最后在应用中注册该模块:

import { createApp } from '@backstage/frontend-defaults';
import catalogCustomizations from './catalog/catalogCustomizations';

const app = createApp({
  features: [catalogCustomizations],
});

export default app.createRoot();

1.5 移除默认过滤器

默认过滤器可以通过 app-config.yaml 将其设为 false 来禁用:

app:
  extensions:
    - catalog-filter:catalog/lifecycle: false
    - catalog-filter:catalog/tag: false
    - catalog-filter:catalog/processing-status: false

二、自定义列、操作与表格选项:覆盖 page:catalog

在旧前端系统中,自定义目录表格的列、行操作和表格选项是通过向 CatalogIndexPage 组件传 props 完成的;在新前端系统中,则需要覆盖 page:catalog 扩展。通过前端模块覆盖页面扩展:

import {
  PageBlueprint,
  createFrontendModule,
  createRouteRef,
} from '@backstage/frontend-plugin-api';

const customCatalogPage = PageBlueprint.make({
  params: {
    path: '/catalog',
    routeRef: createRouteRef({ aliasFor: 'catalog.catalogIndex' }),
    loader: async () => {
      const { CustomCatalogPage } = await import('./CustomCatalogPage');
      return <CustomCatalogPage />;
    },
  },
});

export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [customCatalogPage],
});

在自定义目录页组件内部,你可以完全控制表格列、操作与选项,组合使用 @backstage/plugin-catalog 与 @backstage/plugin-catalog-react 的组件:

import {
  PageWithHeader,
  Content,
  ContentHeader,
  SupportButton,
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { CatalogTable } from '@backstage/plugin-catalog';
import {
  EntityListProvider,
  CatalogFilterLayout,
  EntityKindPicker,
  EntityLifecyclePicker,
  EntityNamespacePicker,
  EntityOwnerPicker,
  EntityProcessingStatusPicker,
  EntityTagPicker,
  EntityTypePicker,
  UserListPicker,
} from '@backstage/plugin-catalog-react';

export const CustomCatalogPage = () => {
  const orgName =
    useApi(configApiRef).getOptionalString('organization.name') ?? 'Backstage';

  return (
    <EntityListProvider pagination>
      <PageWithHeader title={orgName} themeId="home">
        <Content>
          <ContentHeader title="">
            <SupportButton>All your software catalog entities</SupportButton>
          </ContentHeader>
          <CatalogFilterLayout>
            <CatalogFilterLayout.Filters>
              <EntityKindPicker />
              <EntityTypePicker />
              <UserListPicker />
              <EntityOwnerPicker />
              <EntityLifecyclePicker />
              <EntityTagPicker />
              <EntityProcessingStatusPicker />
              <EntityNamespacePicker />
            </CatalogFilterLayout.Filters>
            <CatalogFilterLayout.Content>
              <CatalogTable />
            </CatalogFilterLayout.Content>
          </CatalogFilterLayout>
        </Content>
      </PageWithHeader>
    </EntityListProvider>
  );
};

注意:目录索引页被刻意设计为极小的代码足迹以方便定制,但自行复刻一份页面会引入随时间漂移的风险。建议定期查看目录插件的 CHANGELOG 以跟进默认页面的变化。

关于扩展覆盖的不同模式,详见 extension overrides 文档。

三、实体页(Entity page)与实体谓词(Entity Predicate)

实体页上许多扩展都支持 filter 配置,其作用是筛选该扩展应作用于哪些实体。多数扩展带有默认 filter,你可以通过提供自定义值覆盖它。在代码中定义过滤器时,可以使用谓词函数(predicate function)或实体谓词查询;而在配置(app-config.yaml)中,只能使用实体谓词查询。

3.1 实体谓词查询语法

实体谓词是一种精简的、基于 JSON 的查询语言,用于过滤目录实体。它的灵感来自 MongoDB 的查询语法,行为大致相似但操作符集合不同。

最基本的实体谓词是一个对象表达式:键是实体中值的完整点分隔路径,值是要进行大小写不敏感匹配的目标值。对象中的每一项独立求值,但全部满足时整体才匹配。例如,下面的表达式匹配所有 type 为 service 的 component 实体:

{
  "filter": {
    "kind": "component",
    "spec.type": "service"
  }
}

YAML 语法等价写法:

filter:
  kind: component
  spec.type: service

3.2 逻辑操作符(Logical operators)

实体谓词支持可嵌套的逻辑操作符,包裹在上述对象表达式之上。例如,匹配所有 type 为 service 或 website 的 component 实体:

{
  "filter": {
    "$all": [
      {
        "kind": "component"
      },
      {
        "$any": [{ "spec.type": "service" }, { "spec.type": "website" }]
      }
    ]
  }
}

YAML 写法:

filter:
  $all:
    - kind: component
    - $any:
        - spec.type: service
        - spec.type: website

也可以用值操作符 $in 更简洁地表达同样的语义(见下文 3.4)。

$all

语法:

{ $all: [ { <expression1> }, { <expression2> }, ...] }

当数组中的所有表达式都求值为 true 时,$all 为 true。空数组视为通过,即 { "$all": [] } 永远为 true。

filter:
  $all:
    - kind: component
    - $not:
        spec.type: service

$any

语法:

{ $any: [ { <expression1> }, { <expression2> }, ...] }

当数组中的至少一个表达式求值为 true 时,$any 为 true。空数组视为不通过,即 { "$any": [] } 永远为 false。

filter:
  $any:
    - kind: component
    - metadata.annotations.github.com/project-slug: { $exists: true }

$not

语法:

{ $not: { <expression> } }

$not 取反所提供的表达式结果:表达式为 true 时 $not 为 false,反之亦然。

filter:
  $not:
    kind: template

3.3 值操作符(Value operators)

值操作符可以替代对象表达式中的值。

$exists

语法:

{ field: { $exists: <boolean> } }

当被匹配值的存在状态与提供的布尔值一致时为 true:{ $exists: true } 当且仅当值已定义时为 true;{ $exists: false } 当且仅当值未定义时为 true。

filter:
  metadata.annotations.github.com/project-slug: { $exists: true }

$in

语法:

{ field: { $in: [ <primitive1>, <primitive2>, ... ] } }

当被匹配值存在于该原始值(primitive)数组中时为 true。比较是大小写不敏感的,且只能用于原始值之间;如果被匹配值是对象或数组,该操作符永远为 false。

filter:
  kind:
    $in: [component, api]

$contains

语法:

{ field: { $contains: { <expression> } } }

当被匹配值是一个数组,且数组中至少一个元素完整匹配所给表达式时为 true。如果被匹配值不是数组或数组为空,永远为 false。用于匹配数组元素的表达式可以是任意合法的实体谓词表达式,包括逻辑操作符和值操作符。

filter:
  relations:
    $contains:
      type: ownedBy
      targetRef:
        $in: [group:default/admins, group:default/viewers]

上述示例即可筛选出"被 admins 或 viewers 组拥有"的实体,非常适合用于团队维度的内容展示。

3.4 综合示例:谓词组合

结合逻辑操作符与值操作符,前面"component 且类型为 service 或 website"的查询可以简化为:

filter:
  kind: component
  spec.type:
    $in: [service, website]

从实现角度看,配置中的 filter 字符串最终会通过 buildFilterFn 与 parseFilterExpression 解析为判定函数,相关实现见 plugins/catalog/src/alpha/filter/FilterWrapper.tsx。源码会严格约束"谓词函数与谓词表达式二选一",若同时提供两者会输出警告并优先使用回调函数;若表达式解析出错,也会在控制台输出 Error(s) in entity filter expression 警告,便于排查。

四、配置实体页的组(Groups)、标题与图标

你可以定义并定制实体页上出现的标签页分组(tab groups),同时为组和单个标签页启用图标。配置同样在 page:catalog/entity 下进行:

app:
  extensions:
    # Entity page (new frontend system)
    - page:catalog/entity:
        config:
          # 在组和标签标题旁显示图标
          showNavItemIcons: true

          # 可选:覆盖默认分组及其图标
          groups:
            - overview:
                title: Overview
                icon: dashboard
            - quality:
                title: Quality
                icon: verified
            - documentation:
                title: Docs
                icon: description

注意事项:

  • 组和标签页的图标通过应用的 IconsApi 解析。使用字符串图标 id(例如 "dashboard")时,请确保应用中已启用/安装了对应的图标包(参见 IconBundleBlueprint 相关文档);
  • 只有 showNavItemIcons 为 true 时,组图标才会渲染。

从源码看,page:catalog/entity 的 configSchema 支持 groups(对象数组,每个对象以组名为键,包含 title、可选 icon、可选 aliases、可选 contentOrder)、defaultContentOrder(默认 title)和 showNavItemIcons(默认 false),见 pages.tsx。未配置 groups 时,会使用 defaultEntityContentGroupDefinitions 作为默认分组定义。

4.1 组内内容排序(Content ordering within groups)

默认情况下,每个组内的内容项按标题字母序排序。可以通过 defaultContentOrder 修改,支持两种模式:

  • title(默认)—— 按内容扩展标题的字母序排序(大小写不敏感);
  • natural —— 保持扩展发现/注册的自然顺序。

页面级的 defaultContentOrder 为所有组设置默认排序,单个组可以用组内 contentOrder 覆盖:

app:
  extensions:
    - page:catalog/entity:
        config:
          # 所有组的默认内容顺序
          defaultContentOrder: title

          groups:
            - documentation:
                title: Docs
                # 覆盖:该组保持自然顺序
                contentOrder: natural

注意:内容排序只作用于组内的内容项。未匹配任何分组定义的未分组标签页始终保留自然顺序。

4.2 组别名(Group aliases)

组可以声明 aliases —— 一组应被视为等价的其他组 ID 列表。任何指向别名组 ID 的实体内容扩展都会被归入该别名组。这在重命名或合并分组时非常有用,无需逐个重新配置扩展:

app:
  extensions:
    - page:catalog/entity:
        config:
          groups:
            - develop:
                title: Develop
                # 指向 'development' 的内容将出现在该组
                aliases:
                  - development

4.3 按扩展覆盖或禁用标签页的组

每个实体内容扩展(实体页上的标签页)可以在代码中声明默认的 group。你可以针对单次安装,在 app-config.yaml 中用该扩展的 config 覆盖或禁用分组:

app:
  extensions:
    # ...
    # 示例实体内容扩展实例 id
    - entity-content:example/my-content:
        config:
          # 将该标签页移动到你在上方定义的自定义组
          group: custom
          # 为这个实体内容页显示图标(仅当 page:catalog/entity 启用了 showNavItemIcons)
          icon: my-icon

    # 与任何组解绑,作为独立标签页展示
    - entity-content:example/another-content:
        config:
          group: false

4.4 实体内容的标签页图标

实体内容扩展也可以声明 icon 参数。以字符串提供时,图标 id 通过 IconsApi 查找。图标渲染需要满足两个条件:

  • 实体页必须设置 showNavItemIcons: true(见上方配置);
  • 图标 id 必须存在于应用已启用的图标包中。

五、实体上下文菜单(Entity Context Menu)

实体页右上角的上下文菜单条目可以通过 EntityContextMenuItemBlueprint 配置。当前内置条目定义于 plugins/catalog/src/alpha/contextMenuItems.tsx。

添加一个新菜单项:

import { EntityContextMenuItemBlueprint } from '@backstage/plugin-catalog-react/alpha';
const customEntityMenuItem = EntityContextMenuItemBlueprint.make({
  name: 'open-dialog',
  params: {
    icon: <ExampleIcon />,
    useProps() {
      const dialogApi = useApi(dialogApiRef);
      const { entity } = useEntity();
      return {
        title: 'Open Custom Dialog',
        disabled: false,
        // 也可以使用 href: '/example-path'
        onClick: async () => {
          dialogApi.open(({ dialog }) => (
            <AsyncEntityProvider entity={entity} loading={false}>
              <CustomDialog open onClose={() => dialog.close()} />
            </AsyncEntityProvider>
          ));
        },
      };
    },
  },
});

useProps 返回对象的 onClick 与 href 二选一即可:onClick 适合打开对话框、触发异步操作等交互场景;href 适合直接跳转到指定路径。从源码(pages.tsx)可见,上下文菜单项同样支持可选的 filterFunction 数据引用,用来按实体控制菜单项是否显示。

六、定制实践小结

综合以上内容,在新前端系统中定制软件目录遵循两条清晰的路径:

  1. 纯配置路径:凡是内置扩展支持的能力(分页、导出开关、初始过滤器、移除默认过滤器、实体页分组/图标/排序/别名、按扩展覆盖组),都可以只改 app-config.yaml 的 app.extensions,无需写代码;
  2. 扩展开发路径:当需要新增过滤维度(CatalogFilterBlueprint)、自定义导出格式(CatalogExportConfigBlueprint)、替换整个目录页(PageBlueprint 覆盖 page:catalog)或新增上下文菜单项(EntityContextMenuItemBlueprint)时,通过 createFrontendModule 组装扩展并注册到 createApp 的 features 中。

两种路径都围绕 page:catalog 与 page:catalog/entity 两个核心扩展展开,相关的类型定义与默认实现可继续查阅 plugins/catalog/src/alpha/pages.tsx、plugins/catalog-react/src/alpha/blueprints 及 plugins/catalog/src/alpha/filter/FilterWrapper.tsx,以及更完整的官方文档 software-catalog 文档目录。

登录后查看全文
backstage