Backstage 如何用 entityTransformer 定制 Catalog 与 TechDocs 索引字段【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage当你发现 Backstage 搜索结果中的标题、描述文本不够准确或者想让索引里多带上 tags 之类的字段时需要改的不是搜索引擎配置而是 collator 把实体转换成索引文档的那一步。官方提供的扩展点就是entityTransformer向 Catalog 或 TechDocs 的 collator 工厂注入一个回调控制哪些数据进入搜索索引既可以在默认输出的基础上修改字段也可以为某个kind整体重写索引文档但仍需遵循文档要求的基本结构。本文覆盖两个索引的定制方法backstage/plugin-search-backend-module-catalog的CatalogCollatorEntityTransformer与backstage/plugin-search-backend-module-techdocs的TechDocsCollatorEntityTransformer并给出新、旧两套后端系统的对应写法。先搞清楚默认索引了哪些字段定制之前先看默认转换器生成了什么。Catalog 默认的转换器defaultCatalogCollatorEntityTransformer.ts为每个实体生成以下字段字段默认取值titleentity.metadata.title缺失时回退到entity.metadata.nametext由metadata.description拼接User/Group实体还会加入profile.displayNameUser实体再追加profile.email各段以:连接componentType/typeentity.spec?.type缺失时为othernamespaceentity.metadata.namespace缺失时为defaultkindentity.kindlifecycleentity.spec?.lifecycle缺失时为空字符串ownerentity.spec?.owner缺失时为空字符串TechDocs 侧的TechDocsCollatorEntityTransformer返回类型是PartialOmitTechDocsDocument, location | authorization见 TechDocsCollatorEntityTransformer.ts即允许只返回增量字段向索引文档追加属性。字段修改的硬性限制在写转换器之前记住两条限制它们来自官方文档与类型定义authorization和location两个字段不能通过entityTransformer修改类型定义中已对这两个字段做了Omitlocation只能通过locationTemplate修改而不是 transformer。另外两个模块的扩展点都只允许设置一次TechDocs 侧再次调用会抛出TechDocs collator entity transformer may only be set oncemodule.tsCatalog 侧的setEntityTransformer同样有 can only be called once 限制。也就是说同一个 collator 上注册多份 transformer 是不允许的。新后端系统通过 createBackendModule 注入 transformer新后端系统下collator 由模块自动注册你无法直接调用indexBuilder.addCollator需要用自己的 backend module 依赖模块导出的扩展点来替换 transformer。先确认两个模块已安装在 Backstage 根目录执行yarn --cwd packages/backend add backstage/plugin-search-backend-module-catalog yarn --cwd packages/backend add backstage/plugin-search-backend-module-techdocs定制 Catalog 索引search-backend-module-catalog 的 README给出了完整的写法从主入口导入CatalogCollatorEntityTransformer类型从/alpha入口导入catalogCollatorExtensionPoint然后注册一个 backend module// packages/backend/src/index.ts import { createBackend } from backstage/backend-defaults; import { createBackendModule } from backstage/backend-plugin-api; import { CatalogCollatorEntityTransformer } from backstage/plugin-search-backend-module-catalog; import { catalogCollatorExtensionPoint } from backstage/plugin-search-backend-module-catalog/alpha; const customTransformer: CatalogCollatorEntityTransformer entity ({ title: entity.metadata.title || entity.metadata.name, text: entity.metadata.description || , componentType: entity.spec?.type?.toString() || other, type: entity.spec?.type?.toString() || other, namespace: entity.metadata.namespace || default, kind: entity.kind, lifecycle: (entity.spec?.lifecycle as string) || , owner: (entity.spec?.owner as string) || , }); const backend createBackend(); backend.add(import(backstage/plugin-search-backend)); backend.add(import(backstage/plugin-search-backend-module-catalog)); backend.add( createBackendModule({ pluginId: search, moduleId: my-catalog-collator-options, register(reg) { reg.registerInit({ deps: { collator: catalogCollatorExtensionPoint }, async init({ collator }) { collator.setEntityTransformer(customTransformer); }, }); }, })(), ); backend.start();上面的customTransformer与默认输出字段一一对应你可以在此基础上增删、改写字段。由于返回类型是OmitCatalogEntityDocument, location | authorization完整重写时仍需包含title、text、componentType、type、namespace、kind、lifecycle、owner这些字段。定制 TechDocs 索引TechDocs 模块导出的扩展点是 techdocsCollatorEntityTransformerExtensionPoint它提供两个方法setTransformer(transformer)替换实体到索引文档的转换逻辑setDocumentTransformer(transformer)替换索引文档到最终 search doc 的转换逻辑。写法与 Catalog 侧的 backend module 模式相同在packages/backend/src/index.ts中用createBackendModule依赖该扩展点并在init中调用setTransformer。两者各自只能设置一次重复注册会抛出TechDocs collator entity transformer may only be set once或TechDocs collator document transformer may only be set once。旧后端系统通过 indexBuilder 直接传入 entityTransformer如果你的后端仍使用旧的系统入口形如packages/backend/src/plugins/search.ts通过env.config、indexBuilder.addCollator装配则不需要 backend module直接把回调传给 collator 工厂。Search How-To guides中的官方示例const catalogEntityTransformer: CatalogCollatorEntityTransformer ( entity: Entity, ) { if (entity.kind SomeKind) { return { // customize here output for SomeKind kind }; } return { // and customize default output ...defaultCatalogCollatorEntityTransformer(entity), text: my super cool text, }; }; indexBuilder.addCollator({ collator: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, entityTransformer: catalogEntityTransformer, }), }); const techDocsEntityTransformer: TechDocsCollatorEntityTransformer ( entity: Entity, ) { return { // add more fields to the index tags: entity.metadata.tags, }; }; const techDocsDocumentTransformer: TechDocsCollatorDocumentTransformer ( doc: MkSearchIndexDoc, ) { return { // add more fields to the index bost: doc.boost, }; }; indexBuilder.addCollator({ collator: DefaultTechDocsCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, entityTransformer: techDocsEntityTransformer, documentTransformer: techDocsDocumentTransformer, }), });这段示例展示了三种典型用法按kind分支整体重写第一个if分支、在默认输出基础上追加或覆盖字段展开defaultCatalogCollatorEntityTransformer(entity)后修改text、以及 TechDocs 的增量字段只返回tags因为返回类型允许 partial。注意 TechDocs 侧有两个层面的 transformerentityTransformer作用在实体转索引文档这一步documentTransformer作用在索引文档之后的转换两者可以分别定制。重启后如何确认改动生效索引不是实时的collator 按调度周期性重建索引调度间隔通过 app-config 控制参数分别放在search.collators.catalog和search.collators.techdocs配置键下各模块 README 都说明了这一点具体可选项见各自包内的config.d.ts。因此完整路径是修改 transformer 代码 → 重启后端 → 等待当前索引周期重建 → 在搜索界面按你新增或改写的字段查询确认命中文档的字段内容来自自定义输出。由于location和authorization不受 transformer 影响如果你的定制意图涉及这两个字段应改为配置locationTemplate旧系统下通过 collator 工厂的locationTemplate选项而不是继续改 transformer。小结与限制定制入口新后端系统用createBackendModule 扩展点Catalog 用catalogCollatorExtensionPointTechDocs 用techdocsCollatorEntityTransformerExtensionPoint旧后端系统直接给DefaultCatalogCollatorFactory/DefaultTechDocsCollatorFactory传entityTransformerTechDocs 还可加documentTransformer。硬性边界authorization与location不可经 transformer 修改每个 transformer 扩展点只能设置一次。文档未给出针对索引内容的专用调试接口或断言命令验证只能依赖上述「重建周期 搜索命中字段」的方式如需更细的字段级核对可以对照各模块config.d.ts中调度配置确认重建时机。参考文件Search How-To guides、search-backend-module-catalog README、search-backend-module-techdocs README、TechDocs collator 模块实现。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考