Search How-To 가이드
Search 기능을 구현·사용자 지정하는 방법들을 정리한 가이드 문서예요.
출처: 문서
본문
:::info 이 문서는 새 Backstage 앱에서 기본값인 새 프론트엔드 시스템을 위해 작성됐어요. Backstage 앱이 여전히 이전 프론트엔드 시스템을 사용한다면 이 가이드의 이전 프론트엔드 시스템 버전을 읽으세요. :::
나만의 Search API 구현하는 방법
Search 플러그인은 기본적으로 하나의 주요 API 구현을 제공해요. 바로 검색 결과를 조회하기 위해 search-backend와 통신하는 SearchApi예요.
이 API를 직접 구현해야 하는 경우가 있을 수 있어요. 예를 들어 통신하고 싶은 나만의 검색 백엔드가 있을 때, API를 자신의 요구에 맞게 사용자 지정해야 할 수 있어요. 이 가이드의 목적은 두 단계로 이 과정을 안내하는 것이에요.
- 필요에 따라
SearchApi인터페이스를 구현해요.
export class SearchClient implements SearchApi { // your implementation}
@backstage/frontend-plugin-api의createApiExtension을 사용해 사용자 지정 API 확장을 만들고, 앱에 설치해서 기본 API 확장을 재정의해요. 사용자 지정 API 확장을 만들고 설치하는 방법에 대한 자세한 내용은 Utility APIs 문서를 참고하세요.
Software Catalog 또는 TechDocs 인덱스의 필드를 사용자 지정하는 방법
때로는 catalog 콜레이터에서 어떤 데이터가 검색 인덱스로 들어가는지 제어하거나, 특정 kind에 대해 데이터를 사용자 지정하고 싶을 수 있어요. DefaultCatalogCollatorFactory에 entityTransformer 콜백을 전달하면 쉽게 처리할 수 있어요. 이 동작은 DefaultTechDocsCollatorFactory에서도 가능해요. 기본 동작을 단순히 수정하거나 완전히 새로운 문서(여전히 필요한 기본 구조를 따라야 함)를 작성할 수도 있어요.
authorization과 location은 entityTransformer로 수정할 수 없으며, location은 locationTemplate을 통해서만 수정할 수 있어요.
packages/backend/src/plugins/search.ts
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, }),});
검색 결과 하이라이팅 스타일을 사용자 지정하는 방법
검색 결과에서 일치하는 용어의 기본 하이라이팅 스타일은 <mark> HTML 태그에 대한 브라우저 기본 스타일이에요. 하이라이트된 용어가 어떻게 보이는지 사용자 지정하려면 Backstage의 '앱 UI 사용자 지정' 가이드를 따라 원하는 스타일로 오버라이드를 만들 수 있어요.
예를 들어 통합 테마(unified theming) 방법을 사용하면 다음 결과로 하이라이트된 단어가 굵게(bold) 표시되고 밑줄이 그어져요.
import { createBaseThemeOptions, createUnifiedTheme, palettes, UnifiedTheme,} from '@backstage/theme';export const myLightTheme: UnifiedTheme = createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), defaultPageTheme: 'home', components: { /** @ts-ignore This is temporarily necessary until MUI V5 transition is completed. */ BackstageHighlightedSearchResultText: { styleOverrides: { highlight: { color: 'inherit', backgroundColor: 'inherit', fontWeight: 'bold', textDecoration: 'underline', }, }, }, },});
사용자 지정 테마는 새 프론트엔드 시스템에서 확장으로 설치돼요. 사용자 지정 테마를 설치하는 방법에 대한 자세한 내용은 테마 문서를 참고하세요.
확장을 사용해 검색 결과를 렌더링하는 방법
검색 결과용 확장은 검색 결과 항목을 렌더링하는 데 사용되는 컴포넌트를 사용자 지정할 수 있게 해줘요. 나만의 검색 결과 항목 확장을 제공하거나 플러그인 패키지가 제공하는 것을 사용할 수 있어요.
검색 결과 목록 항목 확장 제공하기
새 프론트엔드 시스템에서 검색 결과 목록 항목 확장은 @backstage/plugin-search-react/alpha의 SearchResultListItemBlueprint를 사용해 만들어요.
plugins/your-plugin/src/extensions.ts
import { SearchResultListItemBlueprint } from '@backstage/plugin-search-react/alpha';export const YourSearchResultListItem = SearchResultListItemBlueprint.make({ name: 'your-result-item', params: { predicate: result => result.type === 'YOUR_RESULT_TYPE', component: async () => { const { YourSearchResultListItem } = await import('./components'); return YourSearchResultListItem; }, },});
그런 다음 확장은 플러그인의 alpha 진입점에서 내보내지며, 플러그인이 설치되면 자동으로 발견돼요.
플러그인이 아니라 앱에서 검색 결과 목록 항목 확장을 제공해야 한다면, 이를 프론트엔드 모듈로 감싸 createApp에 전달해요.
packages/app/src/search/searchModule.ts
import { createFrontendModule } from '@backstage/frontend-plugin-api';import { YourSearchResultListItem } from './YourSearchResultListItem';export const searchCustomizations = createFrontendModule({ pluginId: 'search', extensions: [YourSearchResultListItem],});
packages/app/src/App.tsx
import { createApp } from '@backstage/frontend-defaults';import { searchCustomizations } from './search/searchModule';const app = createApp({ features: [searchCustomizations],});export default app.createRoot();
검색 결과 항목 순서
여러 검색 결과 목록 항목 확장이 설치되면, 검색 페이지는 그들의 predicate 함수에 따라 결과를 렌더링하는 데 사용해요. 주어진 결과에 대한 predicate가 일치하는 첫 번째 확장이 그 결과를 렌더링하는 데 사용돼요. predicate가 없는 확장은 대체(fallback) 렌더러로 동작하며 마지막에 순서가 배치돼야 해요.
결과 항목 확장을 받아들이는 더 구체적인 검색 결과 레이아웃 컴포넌트도 있어요. 해당 문서를 확인하세요: SearchResultList와 SearchResultGroup.