👶🏻 GraphQL로 WordPress를 되살리다

WordPress는 레거시 CMS입니다. 17년 이상 전에 탄생한 이 시스템은, 지금 다시 만든다면 다른 방식으로 작성되었을 PHP 코드로 가득 차 있습니다.

GraphQL은 데이터에 접근하기 위한 현대적인 인터페이스입니다. 「인터페이스」라는 단어에 주목해 주세요. GraphQL은 내부 데이터 시스템이 어떻게 구현되어 있는지를 신경 쓰지 않고, 오직 데이터를 어떻게 노출할 것인지에만 관심을 둡니다.

이 두 가지를 결합하면 어떤 일이 일어날까요? WordPress 데이터에 접근하기 위한 GraphQL 인터페이스는 어떻게 설계해야 할까요?

대략적으로 두 가지 전략을 생각해 볼 수 있습니다.

전통을 존중하고, WordPress 데이터 모델을 그대로 유지하는 매핑을 제공합니다 (수년에 걸쳐 쌓인 기술적 부채도 포함하여)
기술적 부채를 해소하고, 데이터를 추상적이고 WordPress에 종속되지 않는 방식으로 노출하는 인터페이스를 제공합니다

두 접근 방식 모두 장단점이 있으며, 어느 쪽이 맞고 틀리다는 것은 없습니다. 단지 어떤 동작을 다른 것보다 우선시하는 주관적인 선택일 뿐입니다.

플러그인 Gato GraphQL 에서는 후자의 접근 방식을 선택하여, WordPress를 기반으로 WordPress를 위해 동작하면서도 WordPress에 종속되지 않는 (예를 들어, 일관성 없는 이름과 관계를 제거하는) GraphQL 스키마를 만들려 했습니다.

그 결과, GraphQL은 WordPress를 되살립니다. 기반 CMS로서의 WordPress는 그대로이고 레거시 PHP 코드도 변하지 않지만, 데이터 계층은 전통이 아닌 상식에 기반하여 새롭게 만들어질 수 있습니다. 데이터 계층은 사춘기에서 다시 유아기로 돌아가는 것입니다.

GraphQL + WordPress는 환상의 조합

그 결과는 WordPress 데이터 모델을 표현하는 GraphQL 스키마이며, 중첩된 mutation도 지원합니다.

어떻게 구현되었는지 살펴보겠습니다.

WordPress 데이터 모델

WordPress에는 다음과 같은 엔티티가 있습니다.

posts
pages
custom posts
미디어 요소
users
user roles
tags
categories
comments
blocks
meta 속성
기타 (options, plugins, themes 등)

이러한 엔티티들은 계층 구조를 가질 수 있습니다. 예를 들어, post, page, 미디어 요소는 모두 custom post type이며, tags와 categories는 모두 택소노미입니다.

다음은 WordPress 데이터베이스 다이어그램으로, 모든 엔티티의 데이터가 어떻게 저장되는지를 보여줍니다.

WordPress 데이터베이스 다이어그램

매핑이 DB 다이어그램의 완전한 복제인가요?

WordPress 데이터베이스를 GraphQL 스키마로 매핑할 때, 위의 다이어그램을 1:1로 따를 필요가 있을까요?

아니요, 그렇지 않습니다. 데이터베이스 다이어그램은 실제 구현이지만, GraphQL은 클라이언트에서 데이터에 접근하기 위한 인터페이스입니다. 이 두 가지는 관련이 있지만 서로 달라도 됩니다. GraphQL은 데이터베이스를 신경 쓰지 않습니다. SQL 명령으로 생각하거나, wp_posts나 wp_users라는 테이블이 존재한다는 것을 알 필요가 없습니다.

따라서 WordPress의 GraphQL 스키마를 만들 때 데이터베이스 다이어그램을 그대로 따를 필요는 없습니다. 즉, WordPress 데이터 모델이 가진 기술적 부채의 일부를 해소하는 GraphQL 스키마를 만들 수 있습니다.

WordPress 데이터 모델을 GraphQL 스키마로 매핑하기

매핑을 진행해 봅시다. 먼저 원래 엔티티를 가능한 한 type으로 매핑합니다. WordPress 데이터 모델의 엔티티 목록에서 GraphQL 스키마를 위한 다음 type들을 생성합니다.

Post
Page
Media
User
UserRole
PostTag
PostCategory
Comment

그런 다음 모든 type에 기대되는 필드를 추가합니다. 스키마를 표현하기 위해 SDL, 즉 Schema Definition Language를 사용할 수 있습니다. (이는 문서화 목적으로만 사용됩니다. 플러그인 자체는 SDL로 스키마를 코드화하지 않으며, 모두 PHP 코드입니다.)

Post의 필드 (그 외 다수 중에서) 는 다음과 같습니다.

type Post {
  id: ID!
  title: String
  content: String
  excerpt: String
  publishedAt: Date!
}

User의 필드 (그 외 다수 중에서) 는 다음과 같습니다.

type User {
  id: ID!
  name: String
  email: String!
}

대응하는 연결(connection)도 생성합니다. 연결이란 스칼라(숫자나 문자열 등)가 아닌 다른 엔티티를 반환하는 필드입니다. 예를 들어, post에 저자가 있고, user가 posts를 소유한다는 것을 표현합니다.

type Post {
  author: User!
}
 
type User {
  posts: [Post]
}

필드와 연결은 인수를 받을 수도 있습니다. 예를 들어, Post.date를 포맷 가능하게 하고, User.posts에서 항목 검색과 수 제한을 할 수 있게 합니다.

type Post {
  date(format: String): Date!
}
 
type User {
  posts(limit: Int, search: String): [Post]
}

WordPress 데이터 모델의 모든 엔티티에 대해 이 작업을 계속합니다. 완성되면 Voyager 클라이언트(플러그인 메뉴에서 "Interactive Schema"로 이용 가능)를 사용하여 확인할 수 있는 WordPress의 GraphQL 스키마가 완성됩니다.

WordPress의 GraphQL 스키마

이 스키마는 WordPress 데이터베이스 다이어그램과 유사한 부분도 있지만 많은 차이점도 있습니다. 분석해 보겠습니다.

엔티티 없는 작업은 Root 필드로 매핑됩니다

WordPress 데이터베이스 다이어그램은 데이터가 저장되는 방식을 나타내므로 「시작점」이 없습니다. 그러나 GraphQL은 데이터를 검색하기 위한 인터페이스이므로, 쿼리를 실행하기 위한 초기 단계가 필요합니다.

이 초기 단계가 Root type이며, 더 정확하게는 QueryRoot와 MutationRoot라는 두 type(각각 queries와 mutations를 처리)입니다.

이 두 type에는 get_posts(), get_users(), wp_signon()처럼 엔티티에 의존하지 않는 모든 작업을 매핑합니다.

type QueryRoot {
  posts: [Post]!
  users: [User]!
}
 
type MutationRoot {
  logUserIn(username: String, password: String): User
}

필드가 나타내는 작업과 동일한 이름이나 시그니처를 가질 필요는 없습니다. 예를 들어, 필드 이름을 signOn보다 logUserIn으로 하는 것이 더 적합하다고 볼 수 있습니다.

모든 mutation은 MutationRoot 아래에 둡니다

wp_update_post()처럼 특정 엔티티에 의존하는 작업도 있습니다. 이는 어떤 post에 적용됩니다. 대응하는 mutation은 GraphQL 스키마의 MutationRoot type에 추가해야 합니다. 이것이 GraphQL의 사양입니다.

이 작업은 다음과 같이 매핑됩니다.

type MutationRoot {
  updatePost(input: {
    postID: ID!,
    newTitle: String,
    newContent: String
  }): Post
}

이 플러그인은 중첩된 mutation도 지원합니다 (표준 GraphQL 동작이 아니므로 옵트인 기능으로 제공). 이 경우 mutation은 MutationRoot뿐만 아니라 모든 type 아래에 추가할 수 있습니다. 이 경우 다음과 같이 됩니다.

type Post {
  update(input: {
    newTitle: String,
    newContent: String
  }): Post!
}

custom posts 처리하기

GraphQL에는 type 상속이 없습니다. 따라서 CustomPost라는 type을 가지고, Post와 Page가 이를 상속하는 구조를 취할 수 없습니다.

GraphQL은 이 제약을 보완하기 위해 두 가지 수단을 제공합니다. 인터페이스와 union type입니다.

첫 번째로, 스키마에 CustomPost 인터페이스를 만들고 custom post에서 기대되는 모든 필드를 선언하며, Post와 Page가 그 인터페이스를 구현하도록 정의합니다.

interface CustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}
 
type Post implements CustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}
 
type Page implements CustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}

두 번째로, 모든 custom post type을 반환하는 CustomPostUnion type을 스키마에 만듭니다.

union CustomPostUnion = Post | Page

그리고 적절한 경우에 이 type을 반환하는 필드를 정의합니다.

type QueryRoot {
  customPost(id: ID): CustomPostUnion
  customPosts: [CustomPostUnion]!
}
 
type User {
  customPosts: [CustomPostUnion]
}
 
type Comment {
  customPost: CustomPostUnion!
}

보시다시피, GraphQL 스키마에서는 posts를 다루고 있는지 custom posts를 다루고 있는지 명시적으로 구별해야 합니다. 이 둘은 같지 않기 때문입니다! 이 두 가지를 혼용하는 것은 WordPress의 기술적 부채이며, 수정할 수 있습니다.

그렇기 때문에 custom post는 항상 Post가 아닌 CustomPost라고 부르고, custom posts를 다루는 필드는 항상 posts가 아닌 customPosts라고 부르며, custom post의 ID를 받는 필드 인수는 매핑되는 WordPress 함수에서의 이름이 postID라 하더라도 customPostID라고 부릅니다.

이렇게 함으로써 기대하는 동작이 항상 명확해집니다.

필드 User.customPosts는 posts와 pages를 포함한 모든 custom post 목록을 반환할 수 있는 반면, User.posts는 posts만 반환합니다
필드 Root.setFeaturedImageOnCustomPost는 모든 custom post에 대표 이미지를 추가할 수 있습니다 (그래서 setFeaturedImageOnPost라고 부르지 않습니다)

tags (와 categories)를 단일 type으로 묶지 않기

왜 PostTag (PostCategory도 마찬가지)라는 type 이름을 사용하는 걸까요? 단순히 Tag라고 하면 안 되는 걸까요?

왜냐하면, 이 쿼리를 실행할 때 (product를 CPT로 가정), posts와 products의 tags 필드 결과는 항상 다르고 겹치지 않기 때문입니다.

query {
  posts {
    tags {
      id
      name
    }
  }
  products {
    tags {
      id
      name
    }
  }
}

posts에 추가된 tags는 products의 tags를 검색해도 나타나지 않습니다 (반대의 경우도 마찬가지입니다). 단, product가 post_tag 택소노미를 사용하는 경우에는 PostTag type으로 표현할 수도 있습니다. WordPress에서는 이러한 항목들을 동일한 데이터베이스 테이블의 다른 행으로 취급할 수 있어 큰 문제가 아니지만, 강한 타입 시스템을 가진 GraphQL에서는 중요한 구별입니다.

따라서 이러한 엔티티들을 각자의 type으로 분리해 두는 것이 좋은 설계입니다. posts의 tags는 PostTag type으로 반환하고, 커스텀 플러그인이 자체 product CPT를 구현하는 경우 해당 tags에 ProductTag type을 사용해야 합니다.

미디어 아이템에 고유한 정체성 부여하기

WordPress의 미디어 엔티티는 구현상의 편의를 위해 custom post type으로 취급됩니다. 그러나 GraphQL 스키마에서는 이 기술적 부채를 피하고, 미디어 요소를 custom posts가 아닌 고유한 엔티티로 모델링할 수 있습니다.

이에 따라 GraphQL 스키마에서는 다음과 같은 결정이 내려집니다.

customPosts 필드를 쿼리해도 미디어 요소는 가져오지 않습니다
Media type은 CustomPost 인터페이스를 구현하지 않으며, CustomPostUnion type에 포함되지 않습니다
Media type은 custom post type에서 기대되는 excerpt, date, status 등의 필드를 갖지 않습니다. 대신, 미디어 요소에서 기대되는 필드만 갖습니다.

type Media {
  id: ID!
  src: String!
  width: Int
  height: Int
}

enum 식별 및 매핑

WordPress에서는 특정 값 집합에서 고정된 값을 사용하는 경우가 있습니다. 예를 들어, post의 상태는 "publish", "draft", "pending", "trash" 중 하나만 가능합니다.

GraphQL에서는 이것들을 string 대신 enum으로 취급하고, 대응하는 enumeration type을 만들 수 있습니다. GraphQL 표준에 따르면 enum은 대문자로 작성됩니다.

enum CUSTOM_POST_STATUS {
  PUBLISH
  DRAFT
  PENDING
  TRASH
}

그러나 그렇게 하면 WordPress와 직접 상호 작용하기 위해 쿼리를 사용할 수 없게 됩니다. get_posts( [ "post_status" => "PUBLISH" ] )가 작동하지 않기 때문입니다.

그래서 타협안으로, 이러한 enum 값들은 소문자로 유지합니다.

enum CUSTOM_POST_STATUS {
  publish
  draft
  pending
  trash
}

추가 type 매핑

블록은 WordPress 데이터베이스 다이어그램에서 직접 보이지 않습니다. wp_posts에 저장되어 있고 (wp_blocks라는 테이블은 존재하지 않음), 그럼에도 불구하고 독자적인 엔티티입니다.

따라서 블록을 매핑하기 위해 Block type을 도입합니다.

type Post {
  blocks: [Block]
}
 
type Block {
  type: String!
  attributes: JSONObject
}

👶🏻 GraphQL로 WordPress를 되살리다

뉴스레터 구독하기