Backstage 软件目录浏览指南从实体模型到 Catalog 界面操作详解【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage初次登录 Backstage 独立应用standalone app后侧边栏默认选中Home主面板展示的正是软件目录Software Catalog。本文以 docs/getting-started/viewing-catalog.md 为主线结合仓库内实体描述格式与目录定制文档系统讲解目录中四类核心实体Component、Resource、System、Domain的含义、默认过滤器、信息列、行内操作Catalog Actions以及实体详情页的查看方法并辅以源码级佐证帮助你从看到目录进阶到读懂目录、按需定制目录。目录里到底有什么四大核心实体Backstage 的软件目录基于**实体entity**这一统一模型。从源码结构看目录实体在 packages/catalog-model 中建模并在 docs/overview/technical-overview.md#software-catalog-system-model 中给出了完整的软件目录系统模型Software Catalog System Model。当你浏览目录时接触最多的四类实体是Components组件可在源码控制中追踪的独立软件单元可以实现 API 供其他组件消费。一个典型的组件就是开发者眼中的一个软件单元通常对应一个可部署或可链接的制品。Resources资源运行组件所需的物理或虚拟基础设施例如数据库、消息队列等。Systems系统一组相互协作的 Resources 与 Components 的集合通过暴露一个或多个公共 API 来执行某项功能。它向消费方隐藏了组件之间的内部资源与私有 API。Domains领域共享术语、领域模型、指标、KPI、业务目的或文档的 Systems 的集合用于在生态建模层面对大型目录做顶层组织。系统模型还包含User、Group这类组织实体以及API、Location、Type、Template等补充项。目录中实际可出现的实体种类不止上述四类完整的类型清单见 Technical Overview 的 Software Catalog System Model 章节。需要特别说明的是你完全可以创建自定义实体种类Kind。如果组织里存在无法映射到现有实体类型的建模对象可以参考 extending-the-model.md 的 Adding a new kind 一节 新增 Kind同理也可以在现有 Kind 下新增类型Type见 Adding a new type of an existing kind。初始过滤器设置目录默认展示什么首次打开目录时Backstage 只显示满足以下过滤器条件的已注册实体过滤器默认值说明Kind种类Component只显示组件实体Type类型all所有类型Owner所有者Owned默认显示我拥有的实体Lifecycle生命周期目录中实体spec.lifecycle值的列表可选值见下方说明Processing Status处理状态normal只显示处理正常的实体Namespace命名空间实体所属 namespace 的 ID默认通常是default其中Lifecycle对应描述格式文档中 spec.lifecycle必填 定义的取值常用值有experimental、production、deprecatedNamespace对应 namespace可选 字段用于隔离不同团队或环境的实体命名空间。从代码实现看默认过滤器的能力由 plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx 统一装配其内部包含了EntityKindPicker、EntityTypePicker、UserListPicker、EntityOwnerPicker、EntityLifecyclePicker、EntityTagPicker、EntityProcessingStatusPicker、EntityNamespacePicker等过滤器组件各组件源码位于 plugins/catalog-react/src/components 对应子目录。修改 Owner 与 Kind 的初始设置Owner与Kind两个过滤器的初始值可以通过配置修改。在新前端系统new frontend system中目录定制通过app-config.yaml的app.extensions实现例如设置初始 Kind 过滤器为domainapp: extensions: - catalog-filter:catalog/kind: config: initialFilter: domain将初始列表过滤器默认owned改为allapp: extensions: - catalog-filter:catalog/list: config: initialFilter: all完整的目录过滤器定制说明见 Catalog filters默认过滤器也可以通过配置整体禁用例如将catalog-filter:catalog/lifecycle、catalog-filter:catalog/tag、catalog-filter:catalog/processing-status设置为false。每个实体的信息列对每种实体 Kind目录表格会展示一组信息列。以Component的默认列为示例Name组件名称。System可选引用该组件所属的系统对应spec.system。Owner组件所有者对应spec.owner。Type组件类型。常见取值如下你也可以按组织需要 新增类型service后端服务通常暴露 APIwebsite网站library软件库如 npm 模块或 Java 库。Lifecycle生命周期状态experimental实验性或早期非生产组件可靠性保障较低用户可能更倾向选择其他更成熟的组件production已确立、有归属、被维护的组件deprecated处于生命周期末尾、可能在未来被移除的组件。Description可选组件描述。Tags可选用于搜索的标签。Actions行内操作见下文 Catalog Actions。以上Type、Lifecycle、Owner、System的取值语义与必填/可选性与描述格式文档中 Component 一节的spec.type、spec.lifecycle、spec.owner、spec.system字段定义一一对应详见 descriptor-format.md 的 Kind: Component 章节。列是按 Kind 动态生成的从源码看目录表格的列并非写死的固定列表而是按当前实体 Kind 动态生成。核心逻辑位于 plugins/catalog/src/components/CatalogTable/defaultCatalogTableColumnsFunc.tsx默认列由columnFactories.createTitleColumn、createNameColumn名称列带defaultKind以及createEntitySpecificColumns()组合而成基础列包括createSystemColumnSystem 列、createOwnerColumnOwner 列、createSpecTypeColumnType 列当存在 Type 过滤器时自动隐藏、createSpecLifecycleColumnLifecycle 列不同 Kind 的列组合不同例如user只显示描述与标签列domain/system显示 Owner 加描述与标签列而group/template等另有自己的组合。columnFactories的完整实现见 plugins/catalog/src/components/CatalogTable/columns.tsx这是理解为什么不同实体看到的列不一样的第一手证据。自定义列、操作与表格选项如果你需要修改每种 Kind 对应的列可以按照 Customizing columns, actions, and table options 的说明操作。在新前端系统中做法是覆盖page:catalog扩展通过PageBlueprint创建一个指向/catalog路径、routeRef别名catalog.catalogIndex的自定义页面然后在自定义页面组件中自由组合CatalogTable、CatalogFilterLayout以及各个 Picker 组件实现对列、行内操作和分页等表格选项的完全控制。参考示例见 catalog-customization.md。Catalog Actions实体的行内操作目录表格中每个实体行末尾的Actions列提供一组操作从左到右View查看查看定义该实体的catalog-info.yaml文件。Edit编辑编辑定义该实体的catalog-info.yaml文件操作流程见 Updating a Component更新组件。Star收藏将实体标记为收藏favorite之后可以按 Filtering the Catalog过滤目录 中的方式过滤出带星标的实体。这些行内操作并非固定不变同样可通过 Customizing columns, actions, and table options 进行修改例如在新前端系统中通过EntityContextMenuItemBlueprint添加自定义上下文菜单项。查看实体详情在主面板中选中某个实体后会进入该实体的详情页详情内容取决于实体种类。例如选中example-website这样的 Component会展示About实体的元数据如描述、所有者、标签、领域等。Relations实体关系详见 Viewing entity relationships查看实体关系。Links与该实体关联的链接。Has subcomponents指向该组件所属的另一个组件的实体引用。而选中examples这样的 System 实体时除了与 Component 类似的About、Relations、Links之外还会额外显示Has components、APIs和Has Resources因为这些信息正是 System 在系统模型中的语义——它聚合了组件、API 与资源。详情页背后spec 字段如何驱动信息展示实体详情页上出现的这些区块大多来自描述格式文档中定义的字段与关系。以 Component 为例完整字段见 descriptor-format.md 的 Kind: Component 章节spec.owner必填指向所有者默认是Group也可为User的实体引用例如artist-relations-team会生成ownedBy/ownerOf关系spec.system可选指向所属 System 的实体引用会生成partOf/hasPart关系spec.subcomponentOf可选指向另一个 Component 的实体引用表示我是它的一部分对应详情页的Has subcomponents同样生成partOf/hasPart关系spec.providesApis可选组件对外提供的 API 引用数组生成providesApi/apiProvidedBy关系spec.consumesApis可选组件消费的 API 引用数组生成consumesApi/apiConsumedBy关系spec.dependsOn/spec.dependencyOf可选组件间、组件与资源间的依赖关系生成dependsOn/dependencyOf关系。也就是说你在详情页看到的Relations、Has subcomponents、APIs等区块本质上是系统根据实体描述文件中的spec字段自动推导出的关系视图。一张图看懂实体模型系统模型将实体划分为核心实体Core Entities与组织实体Organizational Entities并支持用 System / Domain 做生态建模Core EntitiesComponent、API、ResourceOrganizational EntitiesUser、GroupEcosystem modelingSystem聚合组件、API、资源对外只暴露公共 API、Domain聚合共享术语与业务目标的多个 System。此外还有Location指向其他目录数据来源的标记、Type无固定语义可按需自定义赋值与Template描述脚手架向导参数与执行步骤。关系示例图与完整说明见 Technical Overview 的 Software Catalog System Model 章节。继续深入想了解目录实体的 YAML 描述格式envelope、metadata、relations、status 以及每种 Kind 的字段定义阅读 Descriptor Format of Catalog Entities想掌握按名称、Kind、Type、Owner、Lifecycle、Processing Status、Namespace 等维度过滤目录阅读 Filtering the Catalog想查看实体之间的依赖与归属关系图阅读 Viewing entity relationships想全面定制目录页面过滤器、列、导出、实体页分组与图标等阅读 Catalog Customization。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
