UNPKG

@roottale/cms-mcp

Version:

RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.

123 lines (96 loc) • 4.92 kB
--- title: 사이트 검색 연동 description: 발행된 글과 페이지를 서버에서 안전하게 검색하고 실제 공개 주소로 연결 --- # 사이트 검색 연동 RootTale 검색은 고객 사이트의 **서버**가 공개 CMS API를 호출하는 방식입니다. 검색창은 일반 GET 폼으로 만들되, `ROOTTALE_API_KEY`는 Server Component나 Route Handler 안에서만 사용합니다. 브라우저가 RootTale API를 직접 호출하지 않습니다. ## 권장 구조 ```text 방문자 브라우저 GET /search?q=상담 │ ▼ 고객 사이트 Server Component searchPosts({ type: "all", locale }) │ Authorization: Bearer rtlk_cust_* ▼ RootTale 공개 검색 API tenant + site + locale + published 범위 검색 ``` 이 구조는 API 키를 숨기고, 검색 결과 페이지를 서버 렌더링하며, 고객사와 사이트 경계를 API에서 강제합니다. `NEXT_PUBLIC_ROOTTALE_API_KEY`처럼 공개 환경변수에 키를 넣으면 안 됩니다. ## Next.js 구현 전체 예시는 `examples/nextjs/app/search/page.tsx`에 있습니다. 핵심 흐름은 다음과 같습니다. ```tsx import { fetchCollections, resolveSearchHitPath, searchPosts, } from "@roottale/cms-client/server"; const [hits, collections] = await Promise.all([ searchPosts({ apiKey: process.env.ROOTTALE_API_KEY!, baseUrl: process.env.ROOTTALE_API_BASE, query, type: "all", locale, limit: 20, revalidate: 60, }), fetchCollections({ apiKey: process.env.ROOTTALE_API_KEY!, baseUrl: process.env.ROOTTALE_API_BASE, }).catch(() => []), ]); const results = hits.flatMap((hit) => { const href = resolveSearchHitPath(hit, collections, locale); return href ? [{ hit, href }] : []; }); ``` 사이트 전체 검색은 `type: "all"`을 명시합니다. 이 값을 생략하면 하위 호환을 위해 글(`post`)만 검색합니다. 다국어 사이트는 현재 경로의 `locale`을 검색 API와 `resolveSearchHitPath` 양쪽에 같은 값으로 전달합니다. ## 결과 주소 계산 검색 결과의 `slug`만 보고 `/blog/{slug}`를 직접 만들지 않습니다. `resolveSearchHitPath`는 다음 규칙을 적용합니다. | 콘텐츠 | 공개 주소 | |---|---| | 고정 페이지 | `/{slug}` | | 기본 블로그 글 | `/blog/{slug}` | | 콘텐츠 유형 글 | `/{collection.basePath}/{slug}` | | 다국어 콘텐츠 | 위 주소 앞에 `/{locale}` 추가 | | 상세 화면이 없는 콘텐츠 유형 | `null` — 검색 목록에서 제외 | 따라서 `fetchCollections`가 실패해도 일반 글은 `/blog/{slug}`로 연결할 수 있지만, 공지·자료실 같은 별도 콘텐츠 유형의 주소 정확도를 위해 정상 응답을 권장합니다. ## 검색 범위와 정렬 - API 키에 연결된 tenant와 site 밖의 콘텐츠는 검색하지 않습니다. - 요청한 locale의 `published` 콘텐츠만 반환합니다. - 제목 완전일치 → 제목 부분일치 → 요약 → 본문 순으로 우선합니다. - 같은 점수에서는 최근 발행 콘텐츠가 먼저 나옵니다. - 응답은 카드용 슬림 결과이며 본문 전체는 포함하지 않습니다. 현재 한 요청은 최대 50건입니다. 첫 버전에는 페이지네이션, 형태소 분석, 오타 교정, 동의어 확장이 없습니다. 실제 검색 로그에서 필요성이 확인되면 추가하는 범위입니다. ## 캐시와 새 글 반영 `revalidate`를 지정하면 Next.js 서버 캐시에 검색 응답이 저장됩니다. 예를 들어 `revalidate: 60`이면 발행·수정 후 검색 결과가 최대 약 60초 늦게 바뀔 수 있습니다. 항상 최신 결과가 필요하면 `revalidate: 0`을 사용하되 API 호출량 증가를 고려하세요. 플랫폼 배포 순서는 **migration → API → SDK·고객 사이트**입니다. 검색용 생성 열과 GIN 색인이 먼저 준비되어야 새 API가 안전하게 조회할 수 있습니다. ## 빈 결과와 장애 처리 - 빈 검색어는 API를 호출하지 않고 입력 안내를 표시합니다. - 정상 응답이지만 결과가 없으면 검색어와 함께 `0건` 안내를 표시합니다. - API 장애는 빈 결과와 구분해 “잠시 후 다시 시도” 안내를 표시합니다. - `searchPosts`는 구 API의 `404`에 한해 빈 배열로 처리하고, 그 밖의 오류는 `CmsApiError`로 전달합니다. 검색 입력은 `type="search"`, `name="q"`, 연결된 `<label>`을 사용하고 결과 수는 `aria-live="polite"`로 알립니다. 검색 결과 페이지는 보통 중복·저가치 URL이므로 `robots: { index: false, follow: true }`를 권장합니다. ## HTTP API JavaScript 이외의 서버에서는 `GET /v1/cms/public/search?q=...&type=all&locale=ko&limit=20`을 사용합니다. 쿼리와 응답 필드는 [HTTP API 레퍼런스](./api-reference.md)를 참고하세요.