💬 'Gutenberg과 분리형 애플리케이션'에 대한 새로운 접근 방식 제안

며칠 전, WPGraphQL의 제작자인 Jason Bahl이 Gutenberg and Decoupled Applications를 공개하여 GraphQL과 Gutenberg를 통합하는 3가지 접근 방식의 장단점을 분석했습니다.

그로부터 일주일 전, 그는 Twitter에서도 언급했습니다. Gato GraphQL의 Gutenberg 모델링 접근 방식은 부적절하다고요:

제 의견으로는 이것은 자랑할 만한 것이 아닙니다. GraphQL이 타입이 지정된 스키마로 해결하려는 것 중 하나는 클라이언트에게 예측 가능성과 일관성을 제공하고, 필드 수준까지 원하는 것을 요청할 수 있는 제어권을 클라이언트에게 부여하는 것입니다.

예측 가능한 형태가 없는 와일드카드 「Object」 타입을 반환한다는 것은 서버와 클라이언트 사이에 더 이상 계약이 없으므로 클라이언트 애플리케이션이 언제든지 중단될 수 있음을 의미합니다. 서버가 클라이언트로부터 제어권을 빼앗아 버린 것입니다.

이 글을 통해 저도 이 대화에 참여하겠습니다. Jason의 비판에 대응하면서 제 플러그인의 접근 방식을 설명하고, 왜 그것이 Gutenberg에 실제로 매우 잘 맞는다고 생각하는지 보여드리겠습니다.

COPE를 사용한 Gutenberg 메타데이터 추출

저의 솔루션은 네 번째 접근 방식으로 볼 수 있으며, 내용은 다음과 같습니다:

GraphQL을 구동하기 위한 Gutenberg 데이터를 얻기 위해 PHP 측에 추가 스키마를 만들거나 기존 데이터를 복제하지 않습니다. 대신 COPE(「Create Once, Publish Everywhere」) 전략을 사용하여 블록에 저장된 콘텐츠에서 데이터를 추출합니다.

(COPE는 콘텐츠의 단일 신뢰 소스를 갖고 이를 다양한 애플리케이션에 노출할 수 있는 전략입니다. 우리의 경우 단일 신뢰 소스는 데이터베이스에 저장된 Gutenberg 블록 데이터입니다. COPE와 WordPress에 대한 구현은 이 글에서 설명했습니다.)

최종적으로 GraphQL을 사용하여 모든 블록을 단일 Block 타입에 매핑함으로써 임의의 Gutenberg 블록에 대한 추출 데이터를 검색할 수 있습니다.

이 전략은 절충안이지 결정적인 해결책이 아닙니다

이 전략은 Jason이 지적하는 문제, 즉 서버 측에 스키마가 없어 서버와 클라이언트 사이의 계약을 만들 수 없다는 문제를 해결하지는 않습니다.

COPE가 이 문제를 해결할 수 없는 이유는 저장된 콘텐츠만으로는 스키마를 재구성할 수 없기 때문입니다:

저장된 콘텐츠는 필드의 타입을 나타내지 않습니다
저장된 콘텐츠는 필드의 제약 조건(nullable인지? 양의 정수인지? 문자열이 이메일인지 URL인지?)을 나타내지 않습니다
nullable 필드는 기본값을 가질 수 있는데, 이는 저장된 콘텐츠에 나타나지 않습니다

그러나 COPE 전략과 단일 Block 타입을 사용하여 모든 블록을 표현함으로써, Gato GraphQL은 기존의 한계를 극복한 Gutenberg와의 매우 훌륭한 통합을 구축할 수 있습니다.

이 글 전체에서 설명드리겠습니다.

Gato GraphQL과 Gutenberg의 통합

이 솔루션은 아직 진행 중인 작업이지만, 어떻게 동작할지는 이미 설명할 수 있습니다.

블록마다 다른 타입에 의존하는(WPGraphQL이 WPGraphQL for Gutenberg 플러그인에 의존할 때 하는 방식) 대신, Gato GraphQL은 모든 블록을 표현하는 단일 Block 타입을 제공합니다.

이 쿼리에서 Post.blockDataItems 필드는 게시물에서 Block 요소 목록을 검색합니다(단락, 이미지, 목록 등 다양한 Gutenberg 블록 포함):

{
  post(by: { id: 1499 }) {
    title
    blockDataItems
  }
}

특정 블록의 데이터를 검색하려면 블록의 이름(core/paragraph, core/quote 등)을 기준으로 필터링할 수 있습니다.

이 쿼리에서는 이미지 블록만 검색합니다:

{
  post(by: { id: 1177 }) {
    title
    blockDataItems(
      filterBy: { include: "core/image" }
    )
  }
}

단일 `Block` 타입 살펴보기

이 접근 방식에서 응답은 스키마가 아닌 저장된 콘텐츠에 따라 달라질 수 있습니다. 이 특성은 그 장점(API를 유연하게 만듦)이자 단점(서버-클라이언트 계약을 강제할 수 없음)입니다.

모든 Block 요소는 두 가지 속성을 포함합니다:

name: 블록의 이름(core/paragraph, core/quote 등)
meta: 블록에 포함된 메타데이터

각 Gutenberg 블록은 서로 다르며, 다른 데이터를 포함합니다(단락 콘텐츠, YouTube 동영상, 이미지 소스 URL과 크기 등). 따라서 meta 필드의 응답에 포함된 데이터도 달라집니다.

그 때문에 meta 필드는 GraphQL 스키마의 해당 JSONObject 타입을 통해 단순히 JSON 객체(「원시」 데이터를 포함할 수 있는)로 매핑되었습니다.

이런 응답이 생성됩니다:

{
  "data": {
    "post": {
      "title": "COPE with WordPress: Post demo containing plenty of blocks",
      "blockDataItems": [
        {
          "name": "core/paragraph",
          "attributes": {
            "content": "Lorem ipsum dolor sit amet"
          }
        },
        {
          "name": "core/image",
          "attributes": {
            "src": "https://ps.w.org/gutenberg/assets/banner-1544x500.jpg"
          }
        },
        {
          "name": "core/quote",
          "attributes": {
            "quote": "Etiam tempor orci eu lobortis elementum nibh tellus molestie",
            "cite": "Aristoteles"
          }
        },
        {
          "name": "core/heading",
          "attributes": {
            "size": "xl",
            "heading": "Welcome to my site"
          }
        },
        {
          "name": "core/list",
          "attributes": {
            "items": [
              "First element",
              "Second element",
              "Third element"
            ]
          }
        },
      ]
    }
  }
}

보시다시피 각기 다른 블록이 다른 속성을 검색합니다:

core/paragraph는 content 속성을 가집니다
core/image는 src 속성을 가지며, 선택적으로 width, height, caption 속성을 가집니다(위 응답에는 나타나지 않음)
core/quote는 quote와 cite(인용된 인물을 위한) 속성을 가집니다
core/heading은 header와 size 속성을 가집니다(xl 값은 <h2>를 나타냅니다. COPE가 값을 대상 애플리케이션, 이 경우 웹사이트로부터 분리하기 때문)
core/list는 items 속성을 가지며, 이는 요소의 목록입니다

`JSONObject` 타입이 스펙에 포함되지 않는 이유

위에서 설명한 JSONObject 타입을 통해 GraphQL은 「동적」 필드(모르는 필드 등) 또는 여러 구성을 가질 수 있는 필드(Gutenberg 블록의 경우가 이에 해당)를 검색할 수 있습니다.

현재 GraphQL 스펙은 JSONObject나 Map 타입을 지원하지 않습니다. 지원 추가가 요청되었는데, 그 이유로 다음과 같은 의견이 있습니다:

[...] 이 기능의 부재는 특히 문제가 됩니다. GraphQL이 인터페이스하는 많은 타입 시스템과 서비스에서 지원되기 때문입니다.

이로 인해 서버가 Map을 전송하고 클라이언트가 Map을 원하는데, GraphQL이 Map 지원 없이 중간에 끼어 있는 상황을 처리하기 위해 서버에 커스텀 리졸버를 구현하고 클라이언트에 커스텀 변환을 구현하게 됩니다. 네, 그것은 가능하고 저는 해봤습니다만, GraphQL로 API 스펙을 작성하는 목적을 훼손하는 상당한 보일러플레이트와 추상화가 필요합니다.

이 기능이 스펙에서 지원되지 않는 것은 동적 필드를 다루는 것이 GraphQL의 강력한 타입 지정 동작에 반하여 서버와 클라이언트 간의 계약을 깨뜨리기 때문입니다.

그래도 이 타입은 Gutenberg에 유익할 수 있습니다. 나중에 보여드리겠습니다.

블록마다 다른 타입과 서버 측 레지스트리를 사용할 때의 문제

블록마다 새 GraphQL 타입을 만들 경우, 모든 플러그인이 그 블록을 GraphQL 스키마에 추가해야 합니다. 이는 모든 블록이 제안된 새 서버 측 레지스트리에 속성을 정의함으로써 자동으로 달성될 수 있습니다.

그렇지 않으면 해당 블록은 API에서 사용할 수 없게 되고, 이는 추가적인 결과를 초래할 수 있습니다. 어떤 상황에서는 쿼리된 게시물의 전체 콘텐츠가 신뢰할 수 없게 될 수 있습니다.

이는 GraphQL이 외부 클라우드 기반 서비스와 상호작용하여 게시물의 모든 블록에 어떤 기능을 적용할 때(번역, 문법 수정, SEO 제안, 분석 등을 생각해 보세요) 발생할 수 있습니다.

이에 대한 예시를 살펴보겠습니다.

Gutenberg 4단계에서 다국어 기능이 추가될 예정이므로, @strTranslate 디렉티브를 통해 실행되는 Google Translate API 호출로 플러그인 내 모든 블록을 번역하는 방법을 모델링해 보겠습니다.

(이 초기 API 기반 번역 이후, 사용자는 항상 WordPress 편집기 내에서 번역된 언어로 블로그 게시물을 계속 편집할 수 있습니다.)

각기 다른 블록에는 번역이 필요한 다양한 정보가 포함되어 있습니다:

core/paragraph: 텍스트
core/image: 캡션
core/quote: 인용문 및 인용된 인물(「교장 선생님」과 같은 직함일 수 있으므로)
core/heading: 제목
core/list: 목록의 모든 항목

블록마다 다른 타입을 사용하면 결과 쿼리는 다음과 같을 수 있습니다:

{
  post(by: { id: 1 }) {
    blocks {
      ... on CoreParagraphBlock {
        content @strTranslate
      }
      ... on CoreImageBlock {
        caption @strTranslate
      }
      ... on CoreQuoteBlock {
        quote @strTranslate
        cite @strTranslate
      }
      ... on CoreHeadingBlock {
        heading @strTranslate
      }
      ... on CoreListBlock {
        items @strTranslateList
      }
      ... on EmbedTwitterBlock {
        caption @strTranslate
      }
      ... on EmbedYoutubeBlock {
        caption @strTranslate
      }
      ... on EmbedVimeoBlock {
        caption @strTranslate
      }
    }
  }
}

이런 식으로 계속됩니다. 블록이 많아질수록 이 쿼리는 길어져서 쉽게 100줄 이상으로 늘어납니다.

명백한 문제는 쿼리가 우리가 유지 관리해야 하는 다루기 힘든 존재가 된다는 것입니다.

또한 모든 블록에 대해 작동하게 하려면 커스텀 기능을 도입해야 합니다. 예를 들어 @strTranslate는 CoreListBlock.items에는 작동하지 않습니다. 이는 문자열 목록(즉, [String]을 반환)인데 디렉티브는 String을 기대하기 때문입니다. 따라서 @strTranslateList를 만들어야 합니다.

그러면 core/table에는 자체 커스텀 디렉티브(@strTranslateTable?)가 필요해집니다.

그리고 서드파티 커스텀 블록은 자체 커스텀 디렉티브가 필요할 수 있습니다.

또한 몇 가지 문제가 더 보입니다.

전부 아니면 전무

블로그 게시물에는 WordPress 편집기에 설치된 임의의 블록이 포함될 수 있습니다. 그리고 쿼리를 코딩할 때 게시물이 어떤 블록을 사용하는지 미리 알 수 없습니다.

그렇다면 블록당 하나의 타입을 사용하는 경우, 쿼리에서 처리해야 할 타입의 수는 게시물의 블록 수와 동일하지 않습니다. 대신 WordPress 편집기에 설치된 블록의 수와 동일해집니다.

WordPress 코어와 플러그인 모두 포함하여 사이트에 100개의 블록이 있다면 어떻게 될까요? 그러면 GraphQL 스키마에 매핑된 100개의 타입이 필요합니다. 매핑되지 않은 단 하나가 「콘텐츠 계약」을 깨뜨려, 일부 블록은 영어에서 프랑스어로 번역되고 나머지는 영어로 남을 수 있습니다.

결과적으로 문제가 되는 블록을 포함하든 아니든 번역된 게시물을 더 이상 신뢰할 수 없게 됩니다. 따라서 모든 블록이 레지스트리에 추가되지 않으면 애플리케이션이 신뢰할 수 없게 될 수 있습니다.

새 블록이 설치될 때마다 쿼리를 업데이트해야 합니다

마찬가지로 모든 블록은 GraphQL 쿼리에서 처리되어야 합니다. 즉, 새 블록을 설치할 때마다 애플리케이션 코드로 돌아가서 업데이트하고 재배포해야 합니다.

이것은 단순한 추가 관료주의가 아닙니다: 모든 쿼리가 업데이트될 때까지 애플리케이션을 깨뜨릴 우려 없이 라이브 사이트에 블록을 설치할 수 없게 됩니다.

GraphQL은 WordPress를 위해 존재해야 하며, 그 반대가 아닙니다

JSONObject가 GraphQL 스펙에 추가되지 않은 이유를 다시 생각해보면, 그것이 GraphQL 방식에 맞지 않기 때문입니다.

그러나 여기서 우리가 진정으로 관심을 갖는 것은 GraphQL이 아닙니다. 우리가 신경 쓰는 것은 WordPress이며, 이 경우에는 더 구체적으로 Gutenberg입니다.

GraphQL을 Gutenberg와 통합할 때 GraphQL은 WordPress 컨텍스트 내에서 작동합니다. 즉, WordPress가 GraphQL의 요구 사항을 충족해야 합니다. 하지만 더 중요한 것은 GraphQL이 WordPress의 요구 사항을 충족해야 한다는 것입니다.

그리고 충돌이 발생하는 경우 WordPress가 우선합니다.

어떤 기능이 GraphQL에는 맞지 않지만 Gutenberg에는 맞는 경우, 그것을 고려해야 할까요?

저는 그래야 한다고 생각합니다.

단일 Block 타입이 어떻게 Gutenberg를 더 잘 지원할 수 있는지 살펴보겠습니다.

단일 `Block` 타입으로 이전 문제 해결하기

앞의 예시에 따라 단일 Block 타입을 사용하여 게시물의 모든 블록을 영어에서 프랑스어로 번역하는 것은 다음과 같이 됩니다(또는 이 개념에 근접한 방식으로):

{
  post(by: { id: 1 }) {
    blocks {
      name
      meta
        @advancePointersInArray(paths: "{{ translatablePaths }}")
          @underEachArrayItem
            @strTranslate(from: "en", to: "fr")
    }
  }
}

이게 전부인가요? 전체 쿼리가? 모든 블록을 번역하기 위해? 네.

코어와 플러그인 모두의 이미 존재하거나 아직 만들어지지 않은 모든 블록에 대해 작동할까요? 네.

이 쿼리가 조금 이상해 보이시나요? 그렇다면 Gato GraphQL에서만 지원하는 비표준 GraphQL 기능을 사용하기 때문입니다:

{{ translatablePaths }}는 임베드 가능한 필드로, 필드의 값을 다른 필드나 디렉티브의 인수로 입력하기 위한 것입니다(이 경우 Block 타입은 translatableFields 필드를 가지며, 그 값이 @advancePointersInArray 디렉티브에 주입됩니다)
디렉티브는 다른 디렉티브로 구성될 수 있습니다

어떤 기능이 CMS가 필요로 하는 것을 정확히 충족시키지만 그 기능이 비표준인 경우, 그래도 사용해야 할까요? 저는 그래야 한다고 생각합니다.

이러한 기능들에 대해 GraphQL 스펙에도 요청을 했습니다(받아들여지지 않겠지만):

단일 `Block` 타입의 작동 방식

주의: 기술적인 섹션이 이어집니다.

Block 타입은 translatablePaths 필드를 가지며, 번역이 필요한 JSONObject의 속성 배열을 반환합니다:

core/paragraph는 ["content"]를 반환합니다
core/image는 ["caption"]을 반환합니다
core/quote는 ["quote", "cite"]를 반환합니다
core/heading은 ["header"]를 반환합니다
core/list는 ["items.0", "items.1", "items.2", ...]를 반환합니다

@advancePointersInArray는 메타 디렉티브입니다: 이후 디렉티브의 컨텍스트를 수정합니다. 이후 디렉티브가 쿼리된 JSONObject 내의 하위 요소(단락 블록의 content 속성 등)를 받도록 합니다. 경로 목록은 동일하게 쿼리된 엔터티에서 평가된 translatablePaths 필드를 통해 얻습니다.

그런 다음 @underEachArrayItem은 또 다른 메타 디렉티브로, 쿼리된 엔터티의 요소 목록을 반복하고 반복된 요소에 대한 참조를 다음 디렉티브에 전달합니다. 이 경우 모든 엔터티에 대해 번역할 속성의 전체 목록을 가져오고, 각각은 String 타입이며, 개별 String 요소를 아래로 전달합니다.

마지막으로 @strTranslate 디렉티브는 JSONObject 내에 포함된 String 타입의 요소를 받아 JSONObject 자체 내에서 바로 번역합니다.

이 솔루션이 얼마나 유연한지 주목해 주세요. JSONObject 내의 문자열 경로만 제공하면 값에 접근하고, @strTranslate(또는 다른 디렉티브)로 수정하고, 심지어 DB에 값을 다시 저장하는 것도 가능합니다(이를 달성하기 위한 작업이 현재 진행 중입니다).

core/list에서는 이미 작동합니다. 목록의 모든 요소는 자체 경로(items.0이 배열의 첫 번째 요소 등)를 통해 도달할 수 있고, 각각에서 String 값에 접근하여 @strTranslate에 전달할 수 있으므로 @strTranslateList를 만들 필요가 없습니다.

마찬가지로 core/table에서도 작동합니다. cells 속성을 통해 데이터를 노출하기만 하면 됩니다. 이는 2차원 배열(행을 위한 배열, 열을 포함하는 배열)이 됩니다. 그러면 translatablePaths는 ["cells.0.0", "cells.0.1", "cells.1.0", ...]로 모든 요소에 접근할 수 있습니다.

서드파티 블록에서도 작동합니다. 그를 위해 블록 데이터가 어떻게 저장되는지 주의를 기울이면 속성 경로를 추론할 수 있습니다.

단일 `Block`은 PHP 코드에 기반한 설정이 필요합니다

블록을 매핑하고 메타데이터 속성의 위치를 파악하는 것은 설정을 통해 달성할 수 있습니다. 따라서 매우 유연한 방식으로 처리할 수 있습니다.

Gutenberg에서 블록의 속성을 저장할 수 있는 두 가지 위치가 있습니다: 속성(attribute)으로서, 또는 렌더링된 콘텐츠 내부에.

예를 들어 core/image 블록은 다음과 같이 저장됩니다:

<!-- wp:image {"id":1670,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large">
<img src="https://newapi.getpop.org/wp/wp-content/uploads/2021/01/dynamic-include-first-query.webp" alt="" class="wp-image-1670"/>
</figure>
<!-- /wp:image -->

이 경우 다음과 같습니다:

id, sizeSlug, linkDestination 속성은 attribute로 저장됩니다
src 속성은 렌더링된 콘텐츠 내부에 저장됩니다

이제 API를 쿼리하면 core/image 블록의 응답은 다음과 같습니다:

{
  "data": {
    "blocks": [
      {
        "name": "core/image",
        "meta": {
          "id": 1670,
          "sizeSlug": "large",
          "linkDestination": "none",
          "src": "https://newapi.getpop.org/wp/wp-content/uploads/2021/01/dynamic-include-first-query.webp"
        }
      }
    ]
  }
}

API는 Gutenberg에 저장된 블록을 파싱하여 속성을 검색하는 방법을 알고 있습니다(그것이 COPE 전략입니다). 이 과정은 어느 정도 자동으로 수행될 수 있고, 이후 훅을 통한 수동 입력이나 사용자 인터페이스가 필요합니다.

attribute로 직접 매핑된 속성을 얻는 것은 간단합니다. GraphQL 서버는 이미 블록에서 모든 attribute를 검색하여 속성으로 사용 가능하게 만들 수 있습니다. 또는 노출할 것을 명시적으로 정의하려면 필터 훅을 통해 할 수 있습니다:

$attrs = apply_filters("blockPropsAsAttr:core/image", []);
 
add_filter("blockPropsAsAttr:core/image", function ($attrs) {
  return array_merge($attrs, ['id', 'sizeSlug', 'linkDestination']);
})

콘텐츠에 저장된 속성은 정규식으로 추출할 수 있습니다:

$propRegexes = apply_filters("blockPropsAsRegex:core/image", []);
 
add_filter("blockPropsAsRegex:core/image", function ($propRegexes) {
  $propRegexes['src'] = '/<img src="(.*?)"/';
  return $propRegexes;
})

마지막으로 @strTranslate가 작용할 블록의 번역 가능한 속성을 지정합니다:

$propRegexes = apply_filters("translatableProperties:core/image", []);
 
add_filter("translatableProperties:core/image", function ($properties) {
  $properties[] = 'caption';
  return $properties;
})

이제 이러한 속성들은 여전히 누군가, 아마도 플러그인 개발자가 충족시켜야 합니다. 따라서 서버 측 레지스트리를 갖추면 이 목표 달성에 도움이 됩니다.

하지만 WordPress 커뮤니티가 제안된 서버 측 레지스트리를 추가하고 싶지 않다면 어떻게 될까요? 이 전략은 쉽게 적응할 수 있습니다. 매핑을 PHP 코드로 할 수 있기 때문입니다(방금 보여드린 것처럼).

어떤 블록이 매핑되지 않은 경우, 사용자도 Gutenberg에 대한 약간의 지식만 있으면(GraphQL이나 스키마에 대한 지식은 불필요) 직접 매핑할 수 있습니다.

또한 매핑되지 않은 블록(번역할 수 없는 블록)이 있을 때 GraphQL이 사용자에게 알림을 보내도록 할 수도 있습니다. 조건이 충족되면 @sendEmail 디렉티브를 실행하는 @if 메타 디렉티브를 추가하여 이를 실현할 수 있습니다:

{
  post(by: { id: 1 }) {
    blocks {
      name
      meta
        @advancePointersInArray(paths: "{{ translatablePaths }}")
          @underEachArrayItem
            @strTranslate(from: "en", to: "fr")
        @if(condition: "{{ isTranslatablePathsUnmapped }}")
          @sendEmail(
            to: "{{ root.adminEmail }}",
            subject: "Block with name {{ name }} has 'translatablePaths' unmapped"
          )
    }
  }
}

이 솔루션은 유연하고 단순하며, 개발자가 새로운 기술을 배우거나 Gutenberg 작동 방식을 변경하지 않아도 GraphQL이 WordPress를 위해 봉사할 수 있습니다.

결론

GraphQL과 Gutenberg의 통합이 어떻게 될지(WordPress 코어에 잠재적으로 포함되는 관점에서) 생각할 때, GraphQL이 Gutenberg의 모든 미래 요구 사항을 처리할 수 있는지 확인해야 합니다. 다음에 대한 완전한 지원이 필요합니다:

다국어 블록
Full Site Editing
협업 편집
라이브 사이트에서 서드파티 서비스와의 상호작용

이 모든 것은 가능하면 Gutenberg를 (적어도 크게는) 변경하지 않고 달성되어야 하며, 플러그인 개발자에게 필요한 새로운 작업을 줄여야 합니다.

이를 감안하면 제가 여기서 제안하는 네 번째 접근 방식이 실제로 매우 잘 작동할 수 있다고 믿습니다.

💬 'Gutenberg과 분리형 애플리케이션'에 대한 새로운 접근 방식 제안

뉴스레터 구독하기