Backstage 如何用 entityTransformer 定制 Catalog 与 TechDocs 索引字段？-平芜编程栈

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）为每个实体生成以下字段：

字段	默认取值
`title`	`entity.metadata.title`，缺失时回退到`entity.metadata.name`
`text`	由`metadata.description`拼接；`User`/`Group`实体还会加入`profile.displayName`，`User`实体再追加`profile.email`，各段以`:`连接
`componentType`/`type`	`entity.spec?.type`，缺失时为`'other'`
`namespace`	`entity.metadata.namespace`，缺失时为`'default'`
`kind`	`entity.kind`
`lifecycle`	`entity.spec?.lifecycle`，缺失时为空字符串
`owner`	`entity.spec?.owner`，缺失时为空字符串

TechDocs 侧的TechDocsCollatorEntityTransformer返回类型是Partial<Omit<TechDocsDocument, 'location' | 'authorization'>>（见 TechDocsCollatorEntityTransformer.ts），即允许只返回增量字段，向索引文档追加属性。

字段修改的硬性限制

在写转换器之前记住两条限制，它们来自官方文档与类型定义：

authorization和location两个字段不能通过entityTransformer修改（类型定义中已对这两个字段做了Omit）；
location只能通过locationTemplate修改，而不是 transformer。

另外，两个模块的扩展点都只允许设置一次：TechDocs 侧再次调用会抛出TechDocs collator entity transformer may only be set once（module.ts），Catalog 侧的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与默认输出字段一一对应，你可以在此基础上增删、改写字段。由于返回类型是Omit<CatalogEntityDocument, '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 侧有两个层面的 transformer：entityTransformer作用在实体转索引文档这一步，documentTransformer作用在索引文档之后的转换，两者可以分别定制。

重启后如何确认改动生效

索引不是实时的：collator 按调度周期性重建索引，调度间隔通过 app-config 控制，参数分别放在search.collators.catalog和search.collators.techdocs配置键下（各模块 README 都说明了这一点，具体可选项见各自包内的config.d.ts）。

因此完整路径是：修改 transformer 代码 → 重启后端 → 等待当前索引周期重建 → 在搜索界面按你新增或改写的字段查询，确认命中文档的字段内容来自自定义输出。由于location和authorization不受 transformer 影响，如果你的定制意图涉及这两个字段，应改为配置locationTemplate（旧系统下通过 collator 工厂的locationTemplate选项），而不是继续改 transformer。

小结与限制

定制入口：新后端系统用createBackendModule+ 扩展点（Catalog 用catalogCollatorExtensionPoint，TechDocs 用techdocsCollatorEntityTransformerExtensionPoint）；旧后端系统直接给DefaultCatalogCollatorFactory/DefaultTechDocsCollatorFactory传entityTransformer（TechDocs 还可加documentTransformer）。
硬性边界：authorization与location不可经 transformer 修改；每个 transformer 扩展点只能设置一次。
文档未给出针对索引内容的专用调试接口或断言命令，验证只能依赖上述「重建周期 + 搜索命中字段」的方式；如需更细的字段级核对，可以对照各模块config.d.ts中调度配置确认重建时机。