Backstage 声明式集成搜索插件（Declarative Integrated Search）完整指南

Backstage 声明式集成搜索插件Declarative Integrated Search完整指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文围绕 Backstage 仓库中的 docs/features/search/declarative-integration.md 展开讲解如何在不编写前端代码的前提下通过声明式集成declarative integration在基于新前端系统的 Backstage 应用中启用并定制搜索功能同时结合仓库源码剖析其背后的扩展Extension机制、配置项与自定义扩展开发流程。读完本文你将掌握扩展数据流的核心概念、Search插件的安装与app-config.yaml配置、使用SearchResultListItemBlueprint构建自定义搜索结果项扩展以及noTrack等内置配置项的用法。实验性功能声明声明式集成目前仍处于实验阶段官方不推荐在生产环境使用本文所有内容均以实验/评估用途为前提。一、声明式集成不写代码也能定制 BackstageBackstage 的声明式集成declarative integration理念是通过配置而非代码来定制 Backstage 实例。这意味着应用维护者可以把原本需要在 TypeScript 代码中完成的插件组装、页面挂载、侧边栏导航项注册等工作下沉到app-config.yaml中完成。在新前端系统New Frontend System中所有扩展 Backstage 核心能力的单元都被称为扩展Extension——它可以是一个 API 提供者也可以是一个页面组件甚至是一条路由。扩展之间通过产出物output artifacts和输入inputs进行组合每个扩展产出若干工件这些工件又被其他扩展作为输入消费从而形成一条可组合的扩展链。Search插件正是以这种方式实现搜索功能的典型代表理解扩展的数据流是掌握声明式搜索的基础。二、扩展数据流从搜索结果项到路由渲染上图为仓库中的 search-extensions-example.drawio.svg源码位于docs/assets/search/目录它完整展示了搜索功能中三类扩展的协作方式SearchResultItem扩展id: plugin.search.result.item产出一个组件Component。它通过挂载点plugin.search.page/items把该组件注入到SearchPage扩展的items输入上。SearchPage扩展id: plugin.search.page消费items输入中注入的搜索结果项组件将其组合成一个完整的搜索页面元素并同时产出**路由路径PATH与页面元素ELEMENT**两个工件这两个工件随后通过core.router/routes挂载点注入到CoreRoutes扩展id: core.router。CoreRoutes扩展当浏览器地址与搜索页面路径匹配时渲染对应的页面元素完成从搜索结果项到用户可见页面的完整链路。这一连串输出 → 挂载点 → 输入的关系正是理解声明式Search插件工作方式的关键。三、Search 插件与其提供的扩展3.1 安装仅需一步在声明式集成模式下启用搜索功能只需安装两个包yarn add backstage/plugin-catalog backstage/plugin-search之所以必须同时安装backstage/plugin-catalog是因为Search插件依赖Catalog APIbackstage/plugin-catalog提供了该 API 的扩展实现。安装完成后无需额外注册代码插件扩展即通过新前端系统的自动发现机制生效仓库中的示例应用可参考 packages/app。3.2 Search 插件提供的扩展预设Search插件声明式入口见 plugins/search/src/alpha.tsx提供了一组扩展预设扩展产出物输入去向作用SearchApiSearch API的具体实现挂载到Core的 apis 持有器为整个应用提供搜索查询能力SearchPage高级搜索页面组件期望接收Search搜索结果项组件作为输入以自定义方式渲染搜索结果SearchNavItem侧边栏搜索导航项数据输入到Core的 nav 扩展在主应用侧边栏中显示搜索入口对应到源码plugins/search/src/alpha.tsx 中searchApi通过ApiBlueprint.make声明factory基于discoveryApi与fetchApi构造SearchClient实现searchApiRefsearchPage通过PageBlueprint.makeWithOverrides声明其inputs定义了三个挂载点——items搜索结果项、resultTypes结果类型过滤器、searchFilters搜索过滤器并在loader中把items输入映射给SearchPage组件见 plugins/search/src/alpha/SearchPage.tsx路由路径固定为/search插件通过createFrontendPlugin注册pluginId: search。从源码结构看searchPage的三个输入挂载点设计为未来把过滤器filter也扩展化预留了空间详见下文未来增强机会。四、通过 app-config.yaml 配置 Search 扩展所有Search扩展都可以在app-config.yaml的app.extensions字段中以扩展 ID 作为配置键进行配置。扩展 ID 的命名规则为kind:name例如搜索页面的扩展 ID 为page:search。4.1 禁用搜索页面扩展# app-config.yaml app: extensions: - page:search: false # ✨ 禁用搜索页面将该扩展的值设为false即可关闭搜索页面同时侧边栏入口也会随之消失。4.2 设置搜索页面标题用于侧边栏# app-config.yaml app: extensions: - page:search: # ✨ 自定义标题 config: title: Search Pagetitle配置会显示在侧边栏的搜索导航项上。源码层面searchPage在 plugins/search/src/alpha.tsx 中通过PageBlueprint.makeWithOverrides提供了configSchema其中包含noTrack: z.boolean().default(false)并在渲染侧边栏条目与页面时应用title、icon等默认值。4.3 已知限制目前尚无法在配置文件中为侧边栏项打开模态框modal也无法通过配置文件指定不同的图标——这两个能力已在维护者的规划中。也就是说page:search的图标与交互行为在当前版本中只能使用插件默认实现。五、自定义搜索结果项扩展SearchResultListItemBlueprint插件开发者可以使用backstage/plugin-search-react/alpha导出的SearchResultListItemBlueprint构建自己的搜索结果项扩展。5.1 Blueprint 的源码级参数说明查阅 plugins/search-react/src/alpha/blueprints/SearchResultListItemBlueprint.tsx 可以看到该 Blueprint 的核心定义如下kind: search-result-list-item自动挂载到page:search的items输入即上文的plugin.search.page/items挂载点configSchema内置noTrack: z.boolean().default(false)用于控制是否关闭该结果项的自动埋点params支持三个字段component必需的扩展组件工厂接收{ config: { noTrack?: boolean } }返回一个异步组件predicate可选的结果匹配谓词返回true表示该结果应由本扩展渲染默认谓词恒返回true即渲染所有类型的结果icon可选的结果项图标。在factory内部BluePrint 使用lazy加载component工厂产出的组件并用ExtensionBoundary包裹再通过SearchResultListItemExtension注入rank、result、noTrack等属性最终以searchResultListItemDataRef数据引用输出——这正是SearchPage的items输入所消费的数据格式。对应地plugins/search/src/alpha/SearchPage.tsx 中的getResultItemComponent会遍历items用每个结果项的predicate匹配当前result命中则使用该扩展的component否则回退到DefaultResultListItem渲染。5.2 创建自定义 TechDocs 搜索结果项扩展// plugins/techdocs/src/alpha.tsx import { SearchResultListItemBlueprint } from backstage/plugin-search-react/alpha; export const TechDocsSearchResultListItemExtension SearchResultListItemBlueprint.make({ name: techdocs, params: { predicate: result result.type techdocs, component: async ({ config }) { const { TechDocsSearchResultListItem } await import( ./components/TechDocsSearchResultListItem ); return props TechDocsSearchResultListItem {...props} {...config} /; }, }, });上述代码中插件开发者提供了一个专门渲染type techdocs结果的组件predicate限定只处理 TechDocs 类型的搜索结果component异步加载自定义结果项组件并把config含noTrack透传给渲染组件。该自定义结果项扩展在backstage/plugin-techdocs安装后会默认启用采纳者无需在配置文件中手动启用。仓库中 TechDocs 插件的实际实现见 plugins/techdocs/src/alpha/index.tsxtechDocsSearchResultListItemExtension更进一步使用了makeWithOverrides额外扩展了configSchemaconfigSchema: { title: z.string().optional(), // 可选标题 lineClamp: z.number().default(5), // 结果摘要行数截断 asLink: z.boolean().default(true), // 是否渲染为链接 asListItem: z.boolean().default(true), // 是否渲染为列表项 },并通过predicate: result result.type techdocs与icon: DocsIcon /完善了 TechDocs 专属的结果项行为最终经createFrontendPluginpluginId: techdocs把该扩展注册进插件扩展列表。5.3 禁用内置的 TechDocs 搜索结果项如果采纳者在安装 TechDocs 插件后不想要自定义的 TechDocs 搜索结果项可通过配置禁用# app-config.yaml app: extensions: - search-result-list-item:techdocs: false扩展 ID 中的search-result-list-item正是SearchResultListItemBlueprint的kind源码见 SearchResultListItemBlueprint.tsxtechdocs则是make时指定的name。5.4 使用内置 noTrack 配置关闭自动埋点SearchResultListItemBlueprint内置了noTrack配置项可用于禁用该结果项扩展的自动分析事件追踪# app-config.yaml app: extensions: - search-result-list-item:techdocs: config: noTrack: true源码层面noTrack由 Blueprint 的configSchema声明z.boolean().default(false)默认值为false即默认开启埋点随后被传入SearchResultListItemExtension与你的自定义组件config中。5.5 测试验证仓库中 SearchResultListItemBlueprint.test.tsx 提供了该 Blueprint 的单元测试验证了两个关键行为未提供predicate时使用恒为真的默认谓词测试中显式传入predicate: () true并快照断言扩展的挂载点为page:search/items、kind为search-result-list-itemnoTrack配置会正确传递给组件分别以默认配置与{ config: { noTrack: true } }渲染测试扩展页面分别呈现noTrack: false与noTrack: true证明配置默认值与覆盖传递均生效。这对插件开发者是很好的参考用例——自定义结果项扩展可以按同样的方式用createExtensionTester进行验证。六、未来增强机会扩展替换Extension ReplacementBackstage 维护者正在推进扩展替换能力届时采纳者将可以直接替换插件提供的扩展而不仅仅是启用/禁用相关文档会随版本更新。过滤器扩展化第一版SearchPage扩展的inputsitems、resultTypes、searchFilters设计为搜索插件维护者未来将过滤器也转化为扩展留好了余地。如果你对这个方向感兴趣可以打开 issue 并提交 PR 参与协作。七、小结声明式集成为 Backstage 搜索功能提供了一条低代码路径安装backstage/plugin-catalog与backstage/plugin-search即可获得完整的搜索页面、侧边栏入口与 API通过app.extensions配置可以禁用/定制扩展借助SearchResultListItemBlueprint与predicate/component/icon/noTrack等参数可以快速接入自定义结果项如 TechDocs 的实现方式。由于该能力仍处于实验阶段建议仅在评估与演示环境中使用并持续关注维护者对扩展替换与过滤器扩展化的后续更新。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考