가이드 데이터는 어디서 오나요? — Frontend 데이터 호출 방식 정리
현재 가이드 페이지는 하드코딩된 TypeScript 객체를 불러와 렌더링하고 있습니다. 이 방식의 장단점과 향후 FastAPI(백엔드) 연동, Headless CMS 도입 등 확장 가능한 데이터 아키텍처 옵션들을 비교해 봅니다.
아키텍처 구조도
현재 방식: TypeScript 하드코딩 (Static Data)
지금 여러분이 보고 계신 이 가이드의 텍스트 데이터는 모두 프론트엔드 프로젝트 내부의 `/src/data/guides/*.ts` 파일 안에 직접 작성(하드코딩)되어 있습니다.
import { guides } from '@/data/guides';
export default function GuidePage({ params }) {
// DB나 API 호출 없이 메모리에 올라간 배열에서 바로 검색
const guide = guides.find(g => g.slug === params.slug);
return <div>{guide.title}</div>;
}장점
- •API 서버나 DB가 필요 없어 구조가 매우 단순함
- •네트워크 지연이 없어 렌더링이 가장 빠름 (0ms)
- •TypeScript의 타입 검사를 완벽하게 받을 수 있음
- •초기(MVP) 단계에서 컨텐츠를 빠르게 늘리기 좋음
단점
추천- ✓글 하나를 수정해도 전체 웹사이트를 다시 빌드(Build)하고 배포해야 함
- ✓데이터 양이 많아지면 JavaScript 번들 사이즈가 커짐
- ✓비개발자(에디터, 기획자)가 컨텐츠를 수정하기 어려움
대안 1: 백엔드 API (FastAPI + DB) 연동
가장 일반적인 확장 방식입니다. 가이드 텍스트를 PostgreSQL 같은 데이터베이스에 저장하고, FastAPI 백엔드가 이를 JSON으로 서빙하면 프론트엔드가 호출해서 그리는 방식입니다.
// Next.js Server Component
export default async function GuidePage({ params }) {
// 백엔드 API(FastAPI) 호출
const res = await fetch(`http://server-blue:8000/api/guides/${params.slug}`);
const guide = await res.json();
return <div>{guide.title}</div>;
}장점과 단점
장점: 글을 수정할 때 코드 배포 없이 DB 데이터만 쿼리로 슥 바꾸면 즉시 반영됩니다.
단점: 백엔드 개발(API 설계), DB 모델링, 백엔드 서버 운영 등 관리 포인트가 3배로 늘어납니다.
대안 2: Markdown / MDX 기반 정적 생성
개발자 블로그에서 가장 많이 쓰는 방식입니다. 텍스트를 마크다운(.md) 파일로 저장해두고, Next.js가 빌드 타임에 마크다운을 파싱해서 HTML로 변환합니다.
작성 편의성
복잡한 TS 객체 대신 친숙한 마크다운 문법으로 글을 쓸 수 있습니다.
MDX 확장성
마크다운 안에 <Button /> 같은 React 컴포넌트를 끼워 넣을 수 있습니다.
성능
빌드 시점에 완성된 HTML이 생성(SSG)되므로 로딩이 매우 빠릅니다.
대안 3: Headless CMS 도입
Contentful, Strapi, Sanity 같은 "Headless CMS"를 사용하는 방법입니다. 워드프레스처럼 글을 쓰는 어드민(Admin) 대시보드를 제공하지만, 화면을 그리지 않고 오직 API로 데이터만 던져주는(Headless) 서비스입니다.
언제 Headless CMS를 도입해야 하나요?
컨텐츠를 작성하는 사람(마케터, 에디터)과 화면을 그리는 사람(프론트엔드 개발자)이 분리되어 있을 때 가장 효과적입니다. 개발자는 더 이상 "오타 좀 고쳐주세요"라는 요청을 받지 않아도 됩니다.
그래서 우리는 어떻게 해야 할까?
현재 가이드 컨텐츠가 10~20개 수준이고, 컨텐츠 구조( ContentBlock )가 복잡한 UI 렌더링을 위한 메타데이터를 많이 포함하고 있기 때문에 당분간은 현재의 TypeScript 파일 분리 방식(index.ts)이 가장 비용 효율적(가성비)입니다.
추후 가이드가 50개를 넘어가거나 검색 기능이 고도화되어야 할 때 백엔드 DB 연동이나 MDX 전환을 고려하는 것이 좋습니다.