Wagtail Documentation
헤드리스 지원¶
Wagtail은 헤드리스 사이트에 대한 지원이 잘 되어 있지만, 개발자가 Wagtail을 헤드리스 CMS로 사용할 때 고려해야 할 몇 가지 제한 사항이 있습니다. 이 페이지는 헤드리스 사이트와 관련된 대부분의 주제를 다루며, ✅ (좋은 지원), ⚠️ (해결 방법이 필요하거나 불완전한 지원) 및 🛑 (지원 부족)을 사용하여 문제가 발생할 수 있는 부분을 식별하려고 합니다.
Wagtail은 GitHub에서 #headless 태그가 붙은 이슈 목록을 관리하고 있습니다.
API¶
Wagtail을 헤드리스 CMS로 사용할 때 일반적으로 REST와 GraphQL, 두 가지 인기 있는 API 옵션이 있습니다.
✅ REST¶
REST(또는 REpresentational State Transfer)는 2000년에 HTTP 프로토콜을 사용하여 기계 간 통신을 더 간단하게 하는 접근 방식으로 소개되었습니다. REST가 도입된 이후, RESTful API는 웹 전체로 확산되어 현대 API의 사실상 기본 표준이 되었습니다. 많은 헤드리스 콘텐츠 관리 시스템은 API를 위해 RESTful 아키텍처나 GraphQL을 사용합니다. 두 옵션 모두 헤드리스 Wagtail에서 작동하므로, REST를 선택하는 장단점을 살펴보겠습니다.
REST API의 장점¶
cURL과 같은 일반적인 소프트웨어나 웹 브라우저를 통해 요청을 보낼 수 있습니다.
REST 표준은 오픈 소스이며 비교적 배우기 쉽습니다.
REST는 GET, POST, PUT과 같은 표준 HTTP 액션을 사용합니다.
REST 작업은 다른 비교 가능한 기술(예: SOAP)보다 대역폭이 적게 필요합니다.
REST는 서버 측에서 상태가 없으므로 각 요청이 독립적으로 처리됩니다.
REST에서는 캐싱 관리가 가능합니다.
REST는 현재 더 일반적이며 REST를 지원하는 많은 도구가 있습니다.
REST API는 일부 기능이 이미 내장된 Wagtail의 기본 기능입니다.
REST API의 단점¶
때로는 필요한 데이터를 반환하기 위해 여러 쿼리가 필요합니다.
쿼리가 여러 엔드포인트에 액세스해야 하는 경우 REST는 항상 효율적이지 않을 수 있습니다.
REST API에 대한 요청은 필요하지 않은 추가 데이터를 반환할 수 있습니다.
REST는 업데이트하기 다소 어려울 수 있는 고정된 데이터 구조에 의존합니다.
참고
Wagtail의 내장 REST API를 사용하지 않으려면 Django REST 프레임워크를 사용하여 직접 만들 수 있습니다. Wagtail은 Django일 뿐이라는 것을 기억하세요.
✅ GraphQL¶
GraphQL은 REST보다 더 새로운 API 기술입니다. REST와 달리 GraphQL은 아키텍처가 아니라 API 요청을 단순화하는 데 도움이 되는 데이터 쿼리 언어입니다. GraphQL은 Facebook(현재 Meta)에서 개발했으며 2015년에 오픈 소스로 공개되었습니다. REST보다 더 많은 유연성과 효율성을 제공하도록 설계된 새로운 기술입니다. REST 외에도 GraphQL은 현재 헤드리스 Wagtail에 권장되는 유일한 다른 API 기술입니다. GraphQL을 선택하는 현재의 장단점을 살펴보겠습니다.
GraphQL의 장점¶
상당한 백엔드 업데이트 없이 프로젝트의 클라이언트 측에서 더 빠르게 변경할 수 있습니다.
데이터를 과도하게 가져오거나 부족하게 가져오지 않고 쿼리를 더 정확하고 효율적으로 만들 수 있습니다.
REST에서 여러 엔드포인트가 필요한 데이터를 검색하기 위해 더 적은 쿼리를 사용할 수 있습니다.
GraphQL API는 더 적은 쿼리로 더 적은 리소스를 사용합니다.
GraphQL은 분석 및 성능 모니터링을 위한 옵션을 제공합니다.
GraphQL의 단점¶
GraphQL은 Wagtail에서 기본적으로 지원되지 않습니다.
GraphQL을 사용하려면 라이브러리 패키지를 설치해야 합니다.
현재 GraphQL을 지원하는 도구와 리소스가 더 적습니다.
GraphQL에 익숙한 개발자가 더 적습니다.
GraphQL은 유연성으로 인해 추가적인 성능 및 보안 고려 사항을 도입할 수 있습니다.
Wagtail과 호환되는 GraphQL 라이브러리¶
Torchbox의 wagtail-grapple
Patrick Arminio의 strawberry-wagtail
기능¶
⚠️ 페이지 미리보기¶
현재 미리보기에는 해결 방법이 필요합니다.
현재 공개 API를 사용하여 페이지의 초안 버전을 요청하는 방법이 없습니다. 일반적으로 성숙하고 널리 사용되는 타사 패키지인 wagtail-headless-preview를 권장합니다.
Wagtail에서 자동 저장이 출시되면, API가 모든 상황에서 최신 변경 사항을 제공하므로 미리보기 생성이 덜 장애물이 될 것입니다. 이는 해결 방법을 사용하여 달성할 수 있습니다.
⚠️ 이미지¶
헤드리스 Wagtail에는 추가적인 이미지 고려 사항이 필요합니다.
전통적인 사이트에서 Wagtail은 프론트엔드 개발자가 특정 크기의 이미지를 쉽게 요청할 수 있는 템플릿 태그를 제공합니다. 현재 Wagtail API는 두 가지 솔루션을 제공합니다:
모델에 ImageRenditionField를 추가하여 페이지의 특정 위치에 있는 이미지를 미리 정의된 크기로 요청할 수 있습니다. 대부분의 경우 이 접근 방식을 권장합니다.
동적 이미지 제공 뷰를 사용하면 모든 이미지를 모든 크기로 렌더링할 수 있습니다. 이 접근 방식은 키가 필요하고 키를 주고받을 안전한 방법이 필요하므로 추가 작업이 필요할 수 있습니다. 이것이 없으면 공격자가 수백만 가지의 미묘하게 다른 방식으로 동일한 이미지를 요청하여 사이트를 충돌시킬 위험이 높아집니다.
이러한 솔루션 중 어느 것도 프론트엔드 개발자에게 쉽지 않습니다. 그들은 ImageRenditionField 를 추가할 액세스 권한이나 기술이 없을 수 있으며, 동적 이미지 제공 뷰에 대한 URL을 만드는 것은 서명이 필요하고 현재 JavaScript에서 이 작업을 수행하는 라이브러리나 코드 스니펫이 없기 때문에 까다롭습니다. 해시도 생성해야 하며 현재 JS 버전은 복잡합니다.
⚠️ 페이지 URL 라우팅¶
헤드리스 Wagtail에는 다른 라우팅이 필요합니다.
헤드리스 Wagtail 프로젝트에는 다른 라우팅 접근 방식이 필요합니다. 전통적인 Wagtail 라우팅과 달리, 헤드리스 사이트의 URL 패턴은 일반적으로 프론트엔드 프레임워크(Next.js 또는 Gatsby 등)에서 구성됩니다. Wagtail은 기본적으로 페이지의 슬러그와 페이지 트리의 위치를 사용하여 URL을 페이지로 해석합니다.
이 기본값 때문에 프론트엔드 프레임워크에 구성된 URL 패턴이 페이지 구조와 일치하지 않으면 Wagtail 관리 뷰의 “라이브 보기” 링크가 잘못된 URL로 해석될 수 있습니다. 리치 텍스트가 서버 측에서 렌더링되는 경우, 이는 리치 텍스트 필드의 내부 링크에도 영향을 미칩니다.
헤드리스 Wagtail 프로젝트에서 라우팅에 대한 현재 권장 접근 방식은 사용자 정의 라우트를 만드는 대신 Wagtail 라우트를 사용하는 것입니다. 사용자 정의 라우트를 만들면 더 자주 업데이트하고 유지 관리해야 합니다.
새 사이트가 생성될 때마다 라우트를 구축해야 하며, 이 프로세스를 설명하는 더 나은 문서가 필요합니다. 헤드리스 Wagtail에서 라우팅을 지원하는 장기적인 솔루션 중 하나는 JS 라이브러리나 플러그인을 통해 관리하는 것일 수 있습니다.
⚠️ 리치 텍스트¶
헤드리스 Wagtail에서 리치 텍스트를 처리하는 데는 크게 두 가지 접근 방식이 있습니다:
백엔드에서 렌더링¶
Wagtail은 내부 페이지 링크와 이미지 임베드를 지원하기 위한 일부 사용자 정의 요소가 있는 HTML과 유사한 형식으로 리치 텍스트를 내부적으로 저장합니다. 전통적인 Wagtail 사이트에서는 이러한 사용자 정의 태그가 표준 HTML로 변환되지만, 내장 API에서는 이 작업이 수행되지 않습니다. API는 처리되지 않은 리치 텍스트 콘텐츠를 반환하므로, 사용자는 프론트엔드에서 HTML을 파싱하고 사용자 정의 태그를 변환하거나 백엔드에서 RichText 필드를 렌더링하는 사용자 정의 시리얼라이저를 구현해야 합니다. 현재 wagtail-grapple은 HTML을 미리 렌더링합니다. 따라서 한 가지 해결책은 내장 API를 업데이트하여 HTML도 미리 렌더링하는 것일 수 있습니다.
백엔드에서 렌더링하는 것은 현재 리치 텍스트를 관리하는 데 더 쉬운 접근 방식입니다. 이 접근 방식을 사용하려면 페이지 URL이 Wagtail의 규칙을 따라야 하므로, 복잡한 구성 없이는 사용자 정의 라우팅이 불가능합니다.
프론트엔드에서 렌더링¶
백엔드에서 HTML을 미리 렌더링하는 것이 Wagtail이 렌더링하는 방식에 만족한다면 더 편리할 수 있지만, 프론트엔드에서 렌더링을 사용자 정의하는 것은 여전히 어렵습니다. 다른 헤드리스 CMS는 JSON 형식의 블록 시퀀스로 리치 텍스트를 제공합니다. 이 접근 방식은 HTML 조각을 파싱하는 방법을 찾을 필요 없이 블록의 렌더링을 사용자 정의하기 쉽게 만듭니다.
이 접근 방식은 현재 리치 텍스트를 관리하는 데 더 어려운 접근 방식입니다.
🛑 멀티 사이트 지원¶
멀티 사이트는 헤드리스 Wagtail에서 다르게 작동합니다.
헤드리스 Wagtail에서는 “사이트”의 개념이 다릅니다. 전통적인 Wagtail에서는 Wagtail 사이트의 도메인이나 포트가 Wagtail이 콘텐츠를 제공하는 곳이며 최종 사용자가 사이트를 찾기 위해 방문하는 위치입니다.
그러나 헤드리스 Wagtail에서는 최종 사용자가 사용하는 도메인이나 포트와 Wagtail이 콘텐츠를 제공하는 도메인이나 포트가 다를 것입니다. 예를 들어, 최종 사용자는 www.wagtail.org를 방문할 수 있으며, 웹사이트는 api.wagtail.org에서 실행되는 Wagtail 인스턴스를 쿼리하는 Next.js 앱일 수 있습니다.
Wagtail의 현재 API 구현은 호스트 헤더와 포트를 확인하여 사이트를 찾으므로 해당 사이트 아래의 페이지만 반환합니다. 이는 사이트 레코드가 api.wagtail.org로 설정되어야 함을 의미합니다. 그러나 Wagtail이 URL을 생성할 때, 이러한 URL은 www.wagtail.org에 대해 생성되어야 합니다.
Wagtail API는 기본적으로 사이트 목록이 다른 사이트와 격리되도록 하기 위해 한 번에 하나의 사이트에서만 요청을 허용합니다. 그러나 API는 다음과 같은 방식으로 개선될 수 있습니다:
API 요청에서 사이트를 지정할 수 있도록 합니다.
옵트인 기반으로 모든 사이트의 모든 페이지를 쿼리할 수 있도록 합니다.
이러한 접근 방식을 통해 헤드리스 Wagtail의 Wagtail 관리자에 있는 사이트 레코드는 URL이 올바르게 역전될 수 있도록 최종 사용자가 보는 도메인이나 포트로 설정됩니다. 모든 API 요청은 GET 매개변수로 사이트를 지정합니다.
🛑 양식 제출¶
현재 헤드리스 사이트가 Wagtail 양식에 데이터를 제출하는 데 사용할 수 있는 공식 API가 없습니다.
🛑 비밀번호로 보호된 페이지¶
현재 헤드리스 프론트엔드에서 비밀번호로 보호된 페이지를 볼 수 있는 방법이 없습니다. API는 현재 쿼리에서 모든 비밀번호로 보호된 페이지를 제외합니다.
프론트엔드¶
Wagtail을 위한 프론트엔드를 구축하는 몇 가지 옵션이 있습니다.
⚠️ Next.js¶
Next.js는 헤드리스 Wagtail 웹사이트의 프론트엔드를 구축하기 위해 선택할 수 있는 인기 있는 오픈 소스 JavaScript 프레임워크입니다.
헤드리스 Wagtail에서 Next.js에 대한 특별한 지원은 없지만, Wagtail의 자기 주도적인 Next.js와 Wagtail 가이드나 Github에서 Wagtail과 Next.js를 사용하는 프로젝트를 살펴볼 수 있습니다.
⚠️ Nuxt.js¶
Nuxt.js는 헤드리스 Wagtail 프로젝트의 프론트엔드를 구축하는 데 사용할 수 있는 오픈 소스 JavaScript 프레임워크입니다. NASA의 Jet Propulsion Laboratory를 포함한 여러 유명 사이트가 Wagtail과 Nuxt.js의 조합으로 운영됩니다. 현재 Nuxt.js에 대한 특별한 지원은 없지만, Wagtail의 내장 API는 이를 간단한 옵션으로 만듭니다. 영감과 탐색을 위해 GitHub에서 여러 프로젝트를 사용할 수 있습니다.
⚠️ Gatsby¶
Gatsby는 헤드리스 Wagtail 사이트에 사용할 수 있는 정적 웹사이트를 생성하기 위한 프론트엔드 JavaScript 프레임워크입니다.
현재 헤드리스 Wagtail에서 Gatsby에 대한 특별한 지원은 없습니다. Wagtail을 Gatsby 프론트엔드에 연결하는 데 사용할 수 있는 gatsby-source-wagtail이라는 플러그인이 있습니다. 해당 플러그인을 사용하기로 선택하면 wagtail-grapple 라이브러리에서만 작동하므로 API에 GraphQL 라이브러리를 사용하기로 약속하는 것입니다.
지원 플랫폼¶
프론트엔드 사이트를 호스팅하는 데 사용할 수 있는 많은 플랫폼이 있으며, 다음은 Wagtail과 함께 사용된 일부 플랫폼입니다.
⚠️ Vercel¶
Vercel은 Next.js를 사용하는 개발자 팀을 위한 프론트엔드 플랫폼입니다.
현재 헤드리스 Wagtail과 함께 Vercel을 사용할 수 있는 플러그인은 없습니다. 대부분의 백엔드 서버 렌더링은 어쨌든 새 콘텐츠를 생성할 것이므로, 원하는 경우 플러그인 없이 진행할 수 있습니다.
✅ Netlify¶
Netlify는 헤드리스 Wagtail 사이트의 프론트엔드를 만드는 데 사용할 수 있는 정적 웹사이트 게시 플랫폼입니다.
현재 게시할 때마다 Netlify에 자동으로 핑을 보내 헤드리스 Wagtail 사이트의 새 버전을 빌드하는 wagtail-netify라는 플러그인이 있습니다.