Backstage 旧前端系统下的搜索Search接入与深度定制指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南面向仍在使用**旧前端系统Old Frontend System**的 Backstage 应用完整讲解如何从零接入backstage/plugin-search从前端搜索页面的搭建、路由绑定与侧边栏搜索弹窗到后端搜索插件、搜索引擎Lunr / Postgres与 Collator文档收集器的安装配置并深入源码剖析SearchFilter、useSearch、IndexBuilder等定制点。读完本文你将掌握在旧前端系统下让 Backstage 的 Catalog 与 TechDocs 内容可被全局检索并按自身需求定制过滤、高亮与索引策略的完整实战能力。本文针对使用旧前端系统的应用编写。若你的应用已切换到新前端系统请改读当前版本的指南Getting Started with Search新前端系统。前提Search 是 Backstage 的插件Search 以插件的形式运行在 Backstage 之上因此要使用 Search必须先在本地搭建起一个 Backstage 应用。如果你还没有完成这一步请先参考 Getting Started搭建 Backstage 应用。另外有一个加速路径如果你当初是使用npx backstage/create-app脚手架创建的应用并且packages/app/src/components/search目录下已经存在搜索页面定义那么可以直接跳过下文Adding Search to the Frontend的前半部分从 Customizing Search 一节开始阅读。在旧前端系统中添加 Search 前端1. 安装前端依赖在 Backstage 仓库根目录执行yarn --cwd packages/app add backstage/plugin-search backstage/plugin-search-reactbackstage/plugin-search搜索插件本体提供搜索页面路由组件SearchPage与侧边栏搜索弹窗SidebarSearchModalbackstage/plugin-search-react搜索 Web 库提供SearchBar、SearchResult、SearchFilter、DefaultResultListItem等 React 组件以及useSearch上下文 Hook。2. 创建搜索页面组件在应用中新建文件packages/app/src/components/search/SearchPage.tsx写入以下内容。这是一个典型的搜索页布局顶部是搜索输入框左侧是过滤卡片按kind、lifecycle过滤右侧是结果列表import { Content, Header, Page } from backstage/core-components; import { Grid, List, Card, CardContent } from material-ui/core; import { SearchBar, SearchResult, DefaultResultListItem, SearchFilter, } from backstage/plugin-search-react; import { CatalogSearchResultListItem } from backstage/plugin-catalog; export const searchPage ( Page themeIdhome Header titleSearch / Content Grid container directionrow Grid item xs{12} SearchBar / /Grid Grid item xs{3} Card CardContent SearchFilter.Select namekind values{[Component, Template]} / /CardContent CardContent SearchFilter.Checkbox namelifecycle values{[experimental, production]} / /CardContent /Card /Grid Grid item xs{9} SearchResult {({ results }) ( List {results.map(result { switch (result.type) { case software-catalog: return ( CatalogSearchResultListItem key{result.document.location} result{result.document} highlight{result.highlight} / ); default: return ( DefaultResultListItem key{result.document.location} result{result.document} highlight{result.highlight} / ); } })} /List )} /SearchResult /Grid /Grid /Content /Page );这段代码里有两个值得注意的要点SearchResult使用**渲染属性render prop**模式把结果数组results暴露给你由你自己决定每个结果如何渲染。代码中的result.type是 Collator 定义的类型标识——例如 Catalog Collator 产出software-catalog类型的结果因此switch (result.type)分支里可以针对性使用CatalogSearchResultListItem而其他类型回落到DefaultResultListItem。key使用result.document.locationdocument是搜索文档包含title、text、location等字段location即结果对应的 URL。3. 将搜索页绑定到/search路由在packages/app/src/App.tsx中把上面定义的搜索页绑定到/search路由import { SearchPage } from backstage/plugin-search; import { searchPage } from ./components/search/SearchPage; const routes ( FlatRoutes Route path/search element{SearchPage /} {searchPage} /Route /FlatRoutes );这里SearchPage是插件提供的容器组件负责接入搜索上下文与状态管理而searchPage是你自定义的页面布局。在旧前端系统下搜索页面的逻辑由插件承担而布局完全由应用内的这个组件决定——这也正是 Search Concepts搜索概念 中所说的 The Search Page搜索页是非常个性化的东西插件只替你管理状态布局留在应用里自由发挥。4. 使用侧边栏搜索弹窗Search Modal除了独立搜索页Backstage 还在侧边栏提供SidebarSearchModal组件让用户随时呼出搜索弹窗。在packages/app/src/components/Root/Root.tsx中加入import { SidebarSearchModal } from backstage/plugin-search; export const Root ({ children }: PropsWithChildren{}) ( SidebarPage Sidebar SidebarLogo / SidebarSearchModal / SidebarDivider / {/* ... */} /Sidebar {/* ... */} /SidebarPage );关于Root.tsx的更多用法可查阅packages/create-app的变更记录packages/create-app/CHANGELOG.md中 0.3.15 版本对应的说明。在旧前端系统中添加 Search 后端1. 安装后端插件在 Backstage 仓库根目录执行yarn --cwd packages/backend add backstage/plugin-search-backend backstage/plugin-search-backend-module-pg backstage/plugin-search-backend-module-catalog backstage/plugin-search-backend-module-techdocs各包职责如下包作用backstage/plugin-search-backend搜索后端主插件内置基于 Lunr 的内存搜索引擎backstage/plugin-search-backend-module-pgPostgres 搜索引擎模块backstage/plugin-search-backend-module-catalogCatalog Collator索引软件目录中的实体backstage/plugin-search-backend-module-techdocsTechDocs Collator索引 TechDocs 文档2. 注册后端插件在packages/backend/src/index.ts中加入const backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); // search engines backend.add(import(backstage/plugin-search-backend-module-pg)); // search collators backend.add(import(backstage/plugin-search-backend-module-catalog)); backend.add(import(backstage/plugin-search-backend-module-techdocs)); backend.start();3. 搜索引擎与 Collator 的默认行为完成上述配置后Search 的默认行为是搜索引擎默认使用 Lunr 内存搜索引擎如果你的数据库配置为 Postgres则自动改用 Postgres 作为搜索引擎。更多细节见 Search Engines搜索引擎。Collator自动注册两个 Collator——Catalog 与 TechDocs它们分别负责把软件目录实体与 TechDocs 页面文档化并送入索引从而让这些内容可以被搜索。更多细节见 Collators文档收集器。从概念上讲Backstage Search 本身并不是一个搜索引擎而是你的 Backstage 实例与所选搜索引擎之间的接口层搜索请求经过 Query Translator 翻译成具体引擎的查询语言Collator 把可检索内容收集为符合最小字段约束title、text、location的文档流再由 Indexer 写入对应类型的索引。这一整套抽象在 Search Concepts 中有完整描述。自定义搜索前端内置过滤器SearchFilter.Select 与 SearchFilter.Checkboxbackstage/plugin-search-react通过静态属性暴露了几种默认过滤器组件包括SearchFilter.Select /与SearchFilter.Checkbox /。它们接受与你的 Backstage 实例相关的候选值用户选中后会被传递到后端参与查询过滤CardContent SearchFilter.Select namekind values{[Component, Template]} / /CardContent CardContent SearchFilter.Checkbox namelifecycle values{[production, experimental]} / /CardContent从源码实现看CheckboxFilter通过useSearch()读取/写入搜索上下文中的filters字段见 SearchFilter.tsx勾选/取消时会以name为键合并进setFilters并且不会破坏其他过滤器已写入的数据。values属性还支持传入异步函数(partial: string) PromiseFilterValue[]用于动态加载候选值——此时内部通过useAsyncFilterValues实现 250ms 默认防抖与按输入值缓存见 hooks.ts避免对后端发起过多请求。编写自定义过滤器组件如果默认过滤器满足不了你的需求可以通过useSearch编写自己的过滤器组件Backstage 也欢迎你为核心过滤器贡献新类型import { useSearch, SearchFilter } from backstage/plugin-search-react; const MyCustomFilter () { // Note: filters contain filter data from other filter components. Be sure // not to clobber other filters data! const { filters, setFilters } useSearch(); return (/* ... */); }; // Which could be rendered like this: SearchFilter component{MyCustomFilter} /useSearch暴露的上下文对象包含term、types、filters、pageLimit、pageCursor以及对应的setTerm、setTypes、setFilters等更新方法见 SearchContext.tsx。SearchBar /设置搜索词SearchFilter /组件设置过滤器SearchResult /渲染结果——它们通过同一个搜索上下文互相联动。定制结果列表项与高亮好的搜索结果应当高亮展示因何命中这能帮助用户快速判断结果相关性。以下示例展示了如何为不同类型的结果指定各自的列表项组件SearchResult {({ results }) ( List {results.map(result { // result.type is the index type defined by the collator. switch (result.type) { case software-catalog: return ( CatalogSearchResultListItem key{result.document.location} result{result.document} highlight{result.highlight} / ); // ... } })} /List )} /SearchResult更进阶的前端定制还包括如何实现自己的 Search API当你有自己的搜索后端时可实现SearchApi接口并通过createApiFactory覆盖searchApiRef如何自定义搜索结果的命中高亮样式默认高亮使用浏览器对mark标签的默认样式可通过主题覆盖BackstageHighlightedSearchResultText组件样式实现自定义如何用扩展Extensions渲染搜索结果通过createSearchResultListItemExtensionplugin.provide()暴露结果项渲染扩展并在SearchPage、SidebarSearchModal或自定义SearchModal中组合使用。以上完整指南均可在 Search How-To guides旧前端系统 中查阅。自定义搜索后端用 IndexBuilder 注册任意数量的 CollatorBackstage Search 可以为任何东西建立索引。像 Catalog 这样的插件自带默认 Collator例如DefaultCatalogCollatorFactory负责提供待索引的文档。你可以通过IndexBuilder注册任意数量的 Collatorconst indexBuilder new IndexBuilder({ logger: env.logger, searchEngine }); const every10MinutesSchedule env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 10 }, timeout: { minutes: 15 }, initialDelay: { seconds: 3 }, }); const everyHourSchedule env.scheduler.createScheduledTaskRunner({ frequency: { hours: 1 }, timeout: { minutes: 90 }, initialDelay: { seconds: 3 }, }); indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), }); indexBuilder.addCollator({ schedule: everyHourSchedule, factory: new MyCustomCollatorFactory(), });调整索引重建调度Backstage Search 按调度schedule周期性地完整重建索引见 Search Concepts 中的 The Scheduler 一节。你可以针对不同类型的文档调整索引重建频率——例如文档更新频繁就提高频率反之则降低const every10MinutesSchedule env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 10 }, timeout: { minutes: 15 }, initialDelay: { seconds: 3 }, }); indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), });Lunr 多节点部署时的非分布式调度器:::note 如果使用内存型 Lunr 搜索引擎当你的搜索后端运行多个节点时建议实现一个非分布式的SchedulerServiceTaskRunner以保证一致性或者将搜索插件配置为使用非分布式数据库例如 SQLite。 :::import { SchedulerServiceTaskRunner, SchedulerServiceTaskInvocationDefinition, } from backstage/backend-plugin-api; const schedule: SchedulerServiceTaskRunner { run: async (task: SchedulerServiceTaskInvocationDefinition) { const startRefresh async () { while (!task.signal?.aborted) { try { await task.fn(task.signal); } catch { // ignore intentionally } await new Promise(resolve setTimeout(resolve, 600 * 1000)); } }; startRefresh(); }, }; indexBuilder.addCollator({ schedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), });这个自定义调度器以固定 600 秒10 分钟为间隔循环执行索引刷新任务并在task.signal?.aborted时优雅退出——其语义与每隔 10 分钟重建索引等价但因为是应用内自实现的循环不会依赖分布式调度协调机制从而保证多个搜索后端节点不会互相冲突地重建同一份内存索引。自定义索引字段在旧前端系统的后端定制中还有一个高频需求控制哪些数据进入索引。你可以为DefaultCatalogCollatorFactory或DefaultTechDocsCollatorFactory传入entityTransformerTechDocs 还支持documentTransformer回调来改写/扩充文档字段。需要注意authorization与location不能通过entityTransformer修改其中location只能通过locationTemplate定制。完整示例见 Search How-To guides旧前端系统。延伸阅读Search Concepts核心概念搜索引擎、Query Translator、文档与索引、Collator、Decorator、调度器Search Engines搜索引擎Lunr / Postgres / Elasticsearch 与 OpenSearch 的配置CollatorsCatalog 与 TechDocs Collator 的调度、过滤配置及社区 Collator 列表Search How-To guides旧前端系统新前端系统下的搜索接入指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考