PDF 변환 API의 메타데이터를 동적으로 전환한 이유

PDF 변환 API의 페이지마다 다른 메타데이터를 동적으로 생성하도록 시스템을 재설계했다. 기존 정적 메타데이터에서 벗어나 데이터베이스 기반의 동적 생성 방식으로 전환하면서 설정 파일들도 함께 정리했다.

정적에서 동적으로, 필요했던 변경

PDF 변환 API 같은 경우 문제가 있었다. 각 PDF 파일마다 고유한 제목, 설명, 썸네일 같은 메타데이터가 필요한데, 이걸 소스 코드에 하드코딩하거나 빌드 타임에 고정할 순 없다는 거다. 사용자가 언제 어떤 문서를 업로드하고 변환할지 모르니까.

흔히 마주하는 딜레마다. Next.js 초기 프로젝트는 대부분 layout.tsx에 정적인 generateMetadata를 두고 끝낸다. 하지만 동적 라우팅과 동시에 SEO까지 제대로 챙기려면, 실시간 데이터를 기반으로 메타데이터를 만들어야 한다. 특히 소셜 미디어 공유나 검색 엔진 크롤링에서 정확한 og:title, og:description, og:image 같은 속성들이 없으면 그냥 기본값만 노출되기 쉽다.

설정과 함께 맞춘 구조

변경된 파일들을 보면 세 부분이 함께 움직인다:

next.config.ts: Next.js 자체 설정을 만지는 건 보통 신중한데, 이번엔 동적 메타데이터 생성이 빌드 타임이 아니라 요청 타임에 일어나도록 환경을 조정해야 했다. 정적 생성에서 동적 생성으로 넘어가는 순간 관련 설정들을 검토하는 게 필수다.

src/app/layout.tsx: 여기가 핵심이다. generateMetadata 함수가 요청(request)을 받을 때마다 실행되도록 만들고, seo_db.mjs 모듈에서 데이터를 가져와 메타데이터를 조합한다. 예를 들어 /pdf/document-123 같은 경로의 요청이 들어오면, 데이터베이스에서 document-123에 해당하는 정보를 찾아 og 태그들을 구성하는 식이다.

tsconfig.json: TypeScript 설정은 보통 초기 셋업 이후 자주 안 만지는 부분인데, seo_db.mjs 같은 JavaScript 모듈을 제대로 임포트하고 타입 추론을 받으려면 경로 해석(path resolution)이나 moduleResolution 같은 옵션을 조정해야 할 수 있다.

팀과 미래를 생각한 선택

이런 변경을 할 때 혼자만의 기술적 편의가 아니라, 팀이 이후에 유지보수할 때 얼마나 쉬울지를 먼저 생각한다. 정적 메타데이터면 "배포만 하면 돼"라고 단순하지만, 운영진이나 마케팅팀이 메타데이터를 직접 수정하고 싶을 때 개발자를 부를 수밖에 없다. 반면 DB-driven 방식이면 권한이 있는 사람이 대시보드나 관리 도구를 통해 직접 수정할 수 있다.

또한 PDF 변환 서비스 외에 다른 API들도 같은 패턴을 필요로 할 가능성이 크다. 이미지 최적화 서비스든, 문서 통계 페이지든, 한 번 이런 구조를 만들어두면 새로운 서비스 추가할 때 복사-붙여넣기로 빠르게 확장할 수 있다.

물론 트레이드오프도 있다. DB 쿼리가 매 요청마다 일어나니까 응답 시간이 조금 늘어날 수 있고, 캐싱 전략(Redis나 메모리 캐시)을 함께 고려해야 한다. 하지만 SEO는 검색 엔진 크롤러가 요청하는 것이지 유저가 매번 요청하는 게 아니니까, 캐시 히트율이 충분히 높을 것 같다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.