👨🏻‍💻 GraphQL, 일종의 프로그래밍 언어로서

GraphQL은 GraphQL 언어를 갖추고 있지만, 일반적으로 프로그래밍 언어라고 부르지는 않습니다. 프로그래밍 언어로 할 수 있는 많은 것들을 GraphQL로는 할 수 없기 때문입니다.

GraphQL은 보통 데이터를 가져오는 데 사용됩니다. 예를 들어 클라이언트에서 웹사이트를 렌더링하거나, 데이터를 변경하는 데 사용됩니다. 예를 들어 게시물을 작성하는 경우가 그렇습니다. 기본적으로 이것이 전부입니다.

(다른 용도는 단순히 이 두 가지 경우의 조합입니다. 예를 들어, API 게이트웨이는 클라이언트에 노출되지 않은 내부 서버에서 데이터를 가져오거나 변경할 수 있습니다.)

GraphQL에서 데이터에 접근하는 경우:

query PrintPostTitle($postID: ID!)
{
  post(by: { id: $postID }) {
    title
  }
}

...이것은 PHP에서 다음과 같이 (거의) 동등합니다:

function printPostTitle(int $postID)
{
  $post = getPost($postID);
  echo $post->title;
}

(아래의 모든 예시는 비교를 위한 프로그래밍 언어로 PHP를 사용합니다.)

GraphQL에서 데이터를 변경하는 경우:

query UpdatePost($postID: ID!, $title: String!)
{
  updatePost(
    by: { id: $postID },
    input: { title: $title }
  ) {
    title
  }
}

...이것은 PHP에서 다음과 같이 (거의) 동등합니다:

function updatePost(int $postID, string $title)
{
  $post = getPost($postID);
  $post->update(['title' => $title]);
}

GraphQL은 보통 클라이언트(JavaScript, PHP, Java 등의 프로그래밍 언어로 작성된)에서 접근하며, 클라이언트가 데이터로 무엇을 할지에 대한 로직을 포함하기 때문에 이것으로 충분합니다. 따라서 GraphQL은 단독으로 사용되는 것이 아니라 다른 무언가의 동반자로 사용됩니다.

그러나 GraphQL이 단독으로 사용될 수 있다면, GraphQL만을 사용하여 많은 새로운 유스케이스를 해결할 수 있으며, GraphQL을 새로운 환경에 배포하고 애플리케이션 스택에서 추가적인 작업을 담당하게 할 수 있습니다.

그러기 위해서는 GraphQL이 프로그래밍 언어의 많은 기능을 지원해야 합니다.

GraphQL이 지원하는 프로그래밍 언어 기능은 제한적입니다. 예를 들어, 디렉티브 @include(또는 @skip)를 사용하고 변수를 입력으로 전달하는 것은 (일종의) 조건 로직으로 볼 수 있습니다:

query PrintPostProperties($postID: ID!, $addContent: Boolean!)
{
  post(by: { id: $postID }) {
    title
    content @include(if: $addContent)
  }
}

이 쿼리는 PHP에서 다음과 동등합니다:

function printPostProperties(int $postID, bool $addContent)
{
  $post = getPost($postID);
  echo $post->title;
  if ($addContent) {
    echo $post->content;
  }
}

그것이 기본적인 한계입니다. GraphQL에는 재귀, 동적 변수(값이 런타임에 계산되어 변수에 할당되는 것으로, 딕셔너리에 입력으로 전달되는 것이 아닌), 변수 할당(예: 필드 출력을 변수에 할당하고, 이를 다른 필드의 인수로 제공) 등이 부족합니다.

GraphQL만을 사용하여 다음 문제를 어떻게 해결할지 생각해 보세요:

서비스에 새로운 사용자가 가입할 때마다 해당 서비스에 의해 호출되는 웹훅을 만드세요. 사용자가 뉴스레터를 구독했을 수 있으며(웹훅 페이로드의 marketing_optin 필드로 표시됨), 그 경우 웹훅은 사용자의 이메일(웹훅 페이로드의 email 필드)을 Mailchimp 목록에 등록해야 합니다.

가능하다고 생각하시나요? 쉽나요? 어려운가요? 불가능한가요?

Gato GraphQL에서는 이 문제를 GraphQL만으로 해결하고자 합니다. 그리고 더 많은 문제들도요. 그래서 프로그래밍 언어의 특성을 지원하는 방법에 대해 깊이 고민해 왔습니다.

GraphQL 서버에서 지원한 프로그래밍 기능들을 살펴보겠습니다. 이 글의 마지막에서 그 문제를 어떻게 해결할 수 있는지 확인하겠습니다.

기능성(Functionality)

GraphQL의 필드는 보통 게시물의 제목, 콘텐츠, 데이터와 같은 데이터를 가져옵니다. 하지만 필드를 "기능성"으로 구현할 수도 있습니다.

예를 들어, PHP에서 시간을 출력하는 경우:

function printTime()
{
  echo time();
}

...이것은 GraphQL의 필드 _time으로 구현할 수 있습니다:

{
  _time
}

함수 time은 어떤 타입에도 속하지 않으므로, 필드 _time도 마찬가지입니다. 따라서 이것은 글로벌 필드이며, GraphQL 스키마의 모든 타입에서 접근할 수 있습니다:

{
  posts {
    _time
  }
}

다른 기능성 필드의 예시:

_arrayItem
_arrayJoin
_date
_equals
_inArray
_intAdd
_isEmpty
_isNull
_makeTime
_objectProperty
_sprintf
_strContains
_strRegexReplace
_strSubstr

함수(Functions)

로직의 단위를 함수로 분할하고, 한 함수가 다른 함수를 호출하도록 할 수 있습니다:

function printPostProperties(int $postID)
{
  $post = getPost($postID);
  printPostTitle();
  printPostContent();
}
 
function printPostTitle(Post $post)
{
  echo $post->title;
}
 
function printPostContent(Post $post)
{
  echo $post->content;
}

GraphQL에서도 마찬가지로, 문서의 query(또는 mutation) 작업을 여러 query 작업으로 분할하고, 한 작업이 다른 작업에 "의존"하도록 하여 먼저 실행되게 할 수 있습니다:

query PrintPostTitle($postID: ID!)
{
  postWithTitle: post(by: { id: $postID }) {
    title
  }
}
 
query PrintPostContent($postID: ID!)
{
  postWithContent: post(by: { id: $postID }) {
    content
  }
}
 
query PrintPostProperties
  @depends(on: [
    "PrintPostTitle",
    "PrintPostContent"
  ])
{
  # ...
}

이 쿼리에서 엔드포인트에 ?operationName=PrintPostProperties를 전달하여 GraphQL 쿼리를 실행하면, 먼저 PrintPostTitle과 PrintPostContent 쿼리가 실행되고, 그 후에 PrintPostProperties가 실행됩니다.

이것은 Multiple Query Execution을 통해 가능합니다.

동적 변수(Dynamic Variables)

값을 런타임에 계산하여 변수에 할당할 수 있습니다. 그런 다음 그 값에 따라 어떤 기능을 조건부로 실행할지 결정할 수 있습니다:

function printPostProperties(int $postID)
{
  $post = getPost($postID);
  echo $post->title;
  
  $addContent = isUserLoggedIn();
  if ($addContent) {
    echo $post->content;
  }
}

GraphQL에서는 한 작업에서 동적 변수에 값을 "내보내고", 다른 작업에서 그 값을 읽을 수 있습니다:

query ExportAddContent
{
  addContent: isUserLoggedIn
    @export(as: "addContent")
}
 
query PrintPostProperties($postID: ID!)
  @depends(on: "ExportAddContent")
{
  post(by: { id: $postID }) {
    title
    content @include(if: $addContent)
  }
}

런타임에 계산된 값을 보유하는 변수 $addContent는 PrintPostProperties 작업에서 읽히지만, 해당 작업에서 선언되지 않는다는 점에 주목하세요. 이것이 동적 변수이기 때문입니다.

함수의 조건부 실행

앞의 예시의 대안으로, 로직을 함수로 그룹화한 다음 동적 변수의 값에 따라 함수를 조건부로 실행할지 결정할 수 있습니다:

function printPostProperties(int $postID)
{
  $post = getPost($postID);
  printPostTitle();
  
  $addContent = isUserLoggedIn();
  if ($addContent) {
    printPostContent();
  }
}
 
function printPostTitle(Post $post)
{
  echo $post->title;
}
 
function printPostContent(Post $post)
{
  echo $post->content;
}

GraphQL에서는 작업에 @include 디렉티브를 추가할 수 있습니다:

query ExportAddContent
{
  addContent: isUserLoggedIn
    @export(as: "addContent")
}
 
query PrintPostTitle($postID: ID!)
{
  postWithTitle: post(by: { id: $postID }) {
    title
  }
}
 
query PrintPostContent($postID: ID!)
  @depends(on: "ExportAddContent")
  @include(if: $addContent)
{
  postWithContent: post(by: { id: $postID }) {
    content
  }
}
 
query PrintPostProperties
  @depends(on: [
    "PrintPostTitle",
    "PrintPostContent"
  ])
{
  # ...
}

이제 $addContent가 true인 경우에만 PrintPostContent 작업이 실행됩니다.

변수 할당 및 재입력

앞의 예시를 조금 수정해 보겠습니다. 앞의 예시에서는 조건 "addContent"가 사용자의 로그인 여부에 연결되어 있었습니다.

이 다른 예시에서는, "addContent"는 오늘이 주말일 때 true가 됩니다. 이를 계산하기 위한 로직이 필요합니다:

오늘 날짜 가져오기
날짜를 요일 이름(소문자)으로 형식화하기
"saturday" 또는 "sunday"인지 확인하기

PHP의 경우:

function addContent()
{
  $today = time();
  $dayName = date('l', $today);
  $lcDayName = strtolower($dayName);
  $isWeekend = in_array(
    $lcDayName,
    ['saturday', 'sunday']
  );
  return $isWeekend;
}
 
function printPostProperties(int $postID)
{
  $post = getPost($postID);
  echo $post->title;
 
  $addContent = addContent();
  if ($addContent) {
    echo $post->content;
  }
}

GraphQL의 경우:

query ExportAddContent
{
  today: _time
  dayName: _date(format: "l", timestamp: $__today)
  lcDayName: _strLowerCase(text: $__dayName)
  isWeekend: _inArray(
    value: $__lcDayName
    array: ["saturday", "sunday"],
  )
    @export(as: "addContent")
}
 
query PrintPostProperties($postID: ID!)
  @depends(on: "ExportAddContent")
{
  post(by: { id: $postID }) {
    title
    content @include(if: $addContent)
  }
}

ExportAddContent 작업에서 쿼리된 각 필드의 값은 동적 변수 $__fieldName으로 아래 필드에서 즉시 사용 가능합니다. 이를 통해 필드의 출력을 같은 작업 내에서 즉시 다른 필드의 입력으로 사용할 수 있습니다.

이것은 Field to Input을 통해 가능합니다.

값의 동적 수정

이 PHP 예시에서는 로그인한 사용자가 관리자인 경우 변수의 값을 수정하여, 그 경우 게시물 콘텐츠에 게시물 편집 링크를 추가합니다:

function isAdminUser()
{
  $user = getCurrentUser();
  return in_array("administrator", $user->roles);
}
 
function printPostContent(int $postID)
{
  $post = getPost($postID);
  $postContent = $post->content;
 
  $isAdminUser = isAdminUser();
  if ($isAdminUser) {
    $postContent = sprintf(
      '%s<p><a href="%s">%s</a></p>',
      $postContent,
      $post->edit_url,
      '(Admin only) Edit post'
    ) 
  }
 
  echo $postContent;
}

GraphQL에서는 특정 필드에 대해 다른 값을 생성하는 작업 또는 다른 작업을 조건부로 실행할 수 있습니다:

query InitializeDynamicVariables
{
  isAdminUser: _echo(value: false)
    @export(as: "isAdminUser")
}
 
query ExportConditionalVariables
  @depends(on: "InitializeDynamicVariables")
{
  me {
    roleNames
    isAdminUser: _inArray(
      value: "administrator",
      array: $__roleNames
    )
      @export(as: "isAdminUser")
  }
}
 
query RetrieveContentForAdminUser($postId: ID!)
  @depends(on: "ExportConditionalVariables")
  @include(if: $isAdminUser)
{
  post(by: { id : $postId }) {
    originalContent: content
    wpAdminEditURL
    content: _sprintf(
      string: "%s<p><a href=\"%s\">%s</a></p>",
      values: [
        $__originalContent,
        $__wpAdminEditURL,
        "(Admin only) Edit post"
      ]
    )
  }
}
 
query RetrieveContentForNonAdminUser($postId: ID!)
  @depends(on: "ExportConditionalVariables")
  @skip(if: $isAdminUser)
{
  post(by: { id : $postId }) {
    content
  }
}
 
query ExecuteAll
  @depends(on: [
    "RetrieveContentForAdminUser",
    "RetrieveContentForNonAdminUser"
  ])
{
  # ...
}

같은 동적 변수를 입력으로 @include와 @skip 디렉티브를 사용함으로써, RetrieveContentForAdminUser와 RetrieveContentForNonAdminUser 작업은 상호 배타적이 됩니다.

배열 반복 처리

배열의 항목을 반복 처리하여 해당 값들을 대문자로 변환하고 싶다고 가정해 봅시다:

function printUserRolesAsUppercase(int $userID)
{
  $user = getUser($userID);
  foreach ($user->roles as $role) {
    echo strtoupper($role);
  }
}

GraphQL에서는 디렉티브 @underEachArrayItem으로 배열 항목을 반복 처리하고, 각 값을 체인의 다음 디렉티브(이 경우 @strUpperCase)에 전달할 수 있습니다:

query PrintUserRolesAsUppercase($userID: ID!)
{
  user(by: { id: $userID }) {
    roles
      @underEachArrayItem
        @strUpperCase
  }
}

이것은 컴포저블 디렉티브를 통해 가능합니다.

대량 CRUD 작업

CRUD는 Create(생성), Read(읽기), Update(수정), Delete(삭제)의 약자로, 리소스(게시물, 사용자 등)에 적용하는 작업입니다.

PHP에서 대량 읽기는 다음과 같습니다:

function getPostTitles()
{
  $posts = getPosts();
  foreach ($posts as $post) {
    echo $post->title;
  }
}

이 유스케이스는 GraphQL에서 자연스럽게 해결됩니다:

query GetPostTitles
{
  posts {
    title
  }
}

PHP에서 대량 수정은 다음과 같습니다:

function updatePostTitlesAsUppercase()
{
  $posts = getPosts();
  foreach ($posts as $post) {
    $post->update(['title' => strtoupper($post->title)]);
  }
}

GraphQL에서 대량 수정은 보통 모든 게시물의 데이터를 받는 전용 mutation updatePosts를 생성하여 지원합니다.

저는 이 접근 방식이 마음에 들지 않습니다. 스키마의 mutation 수를 사실상 두 배로 늘리고(하나의 리소스를 변경하는 것, 여러 리소스를 변경하는 것), 두 가지 모두의 로직을 유지해야 하기 때문입니다:

updatePost + updatePosts
createPost + createPosts
등

제 생각에는 더 우아한 접근 방식은 중첩 mutation을 사용하는 것입니다. 여기서 mutation Post.update가 쿼리된 각 리소스에 적용됩니다:

mutation UpdatePostTitlesAsUppercase
{
  posts {
    title
    ucTitle: _strUpperCase(text: $__title)
    update(
      input: { title: $__ucTitle }
    ) {
      status
      post {
        title
      }
    }
  }
}

같은 접근 방식이 리소스 삭제에도 작동합니다:

function deletePosts()
{
  $posts = getPosts();
  foreach ($posts as $post) {
    $post->delete();
  }
}

GraphQL의 경우:

mutation DeletePosts
{
  posts {
    delete {
      status
    }
  }
}

생성의 경우, 리소스가 아직 존재하지 않으므로 전달하지 않습니다. 대신, 생성할 모든 리소스의 데이터 입력이 담긴 배열을 제공합니다:

function createPosts()
{
  $postDataItems = [
    [
      'title' => 'First title',
      'content' => 'First content',
    ],
    [
      'title' => 'Second title',
      'content' => 'Second content',
    ],
  ];
  foreach ($postDataItems as $postDataItem) {
    $post = new Post($postDataItem['title'], $postDataItem['content']);
    $post->save();
  }
}

단일 createPost mutation을 사용하여 GraphQL에서 대량으로 게시물을 생성하는 것은 다소 복잡하지만 충분히 가능합니다.

아이디어는 데이터 입력 배열을 반복 처리하고, 각각을 동적 변수 $input에 할당한 다음, 그 입력을 전달하여 createPost mutation을 실행하는 것입니다. 마지막으로 동적 변수 $createdPostIDs에서 생성된 게시물의 결과 ID를 가져와 해당 데이터를 조회합니다:

mutation CreatePosts
  @depends(on: "GetPostsAndExportData")
{
  createdPostIDs: _echo(value: [
    {
      title: "First title",
      content: "First content"
    },
    {
      title: "Second title",
      content: "Second content"
    },
  ])
    @underEachArrayItem(
      passValueOnwardsAs: "input"
    )
      @applyField(
        name: "createPost"
        arguments: {
          input: $input
        },
        setResultInResponse: true
      )
    @export(as: "createdPostIDs")
}
 
query RetrieveCreatedPosts
  @depends(on: "CreatePosts")
{
  createdPosts: posts(
    filter: {
      ids: $createdPostIDs,
    }
  ) {
    title
    content
  }
}

HTTP 요청 전송(및 기타 함수)

웹 서버에 HTTP 요청을 전송하는 것은 PHP에서 file_get_contents나 curl_exec 같은 전용 함수로 처리할 수 있습니다.

file_get_contents 사용:

$xml = file_get_contents("http://www.example.com/file.xml");

GraphQL에서는 HTTP 요청 실행 로직을 _sendHTTPRequest와 같은 기능성 필드로 처리할 수 있습니다:

query {
  _sendHTTPRequest(input: {
    url: "http://www.example.com/file.xml",
    method: GET
  }) {
    xml: body
  }
}

같은 개념이 모든 기능에 적용됩니다.

예를 들어, PHP에서 상수 값에는 다음과 같이 접근합니다:

$mailchimpUsername = constant('MAILCHIMP_API_CREDENTIALS_USERNAME');

GraphQL에서 해당하는 기능성 필드를 구현할 수 있습니다:

{
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
}

GraphQL만을 사용하여 과제 해결하기

지금까지 살펴본 모든 프로그래밍 언어 기능을 사용하여, 앞서 제시한 문제를 GraphQL만으로 해결할 수 있게 되었습니다:

서비스에 새로운 사용자가 가입할 때마다 해당 서비스에 의해 호출되는 웹훅을 만드세요. 사용자가 뉴스레터를 구독했을 수 있으며(웹훅 페이로드의 marketing_optin 필드로 표시됨), 그 경우 웹훅은 사용자의 이메일(웹훅 페이로드의 email 필드)을 Mailchimp 목록에 등록해야 합니다.

해결책은 GraphQL 퍼시스티드 쿼리를 웹훅으로 사용하고, 다음 쿼리를 실행하는 것입니다:

query HasSubscribedToNewsletter {
  hasSubscriberOptIn: _httpRequestHasParam(name: "marketing_optin")
  subscriberOptIn: _httpRequestStringParam(name: "marketing_optin")
  isNotSubscriberOptInNAValue: _notEquals(value1: $__subscriberOptIn, value2: "NA")
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    @export(as: "subscribedToNewsletter")
}
 
query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  subscriberEmail: _httpRequestStringParam(name: "email")
  
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
   
  mailchimpPassword: _env(name: "MAILCHIMP_API_CREDENTIALS_PASSWORD")
   
  
  mailchimpListMembersJSONObject: _sendJSONObjectItemHTTPRequest(input: {
    url: "https://us7.api.mailchimp.com/3.0/lists/{listCode}/members",
    method: POST,
    options: {
      auth: {
        username: $__mailchimpUsername,
        password: $__mailchimpPassword
      },
      json: {
        email_address: $__subscriberEmail,
        status: "subscribed"
      }
    }
  })
}

이 해결책에서, Mailchimp API에 HTTP 요청을 실행하는 MaybeCreateContactOnMailchimp 작업은 marketing_optin 필드의 값에 따라 조건부로 실행됩니다.

(이 쿼리의 동작 방식은 블로그 게시물 👨🏻‍🏫 GraphQL query to automatically send the newsletter subscribers from InstaWP to Mailchimp에서 확인하세요.)

GraphQL은 생각했던 것보다 훨씬 강력합니다!

GraphQL은 데이터를 가져오고 변경하는 것 그 이상에 사용될 수 있습니다... 데이터 적응, 출력의 동적 수정, 다양한 컨텍스트에 맞는 콘텐츠 맞춤화, 단 몇 줄의 코드로 API 게이트웨이 생성 등 다양한 용도가 있습니다.

프로그래밍 언어 기능을 지원함으로써, 위의 과제를 GraphQL만으로 해결하고 함께 배포할 클라이언트를 불필요하게 만들 수 있습니다. 이를 통해 애플리케이션 스택을 단순화할 수 있습니다: 움직이는 부품이 적어지고, 복잡성이 줄어들며, 디버깅해야 할 코드가 줄어들고, 다뤄야 할 기술이 적어집니다.

GraphQL은 정말 대단합니다 🤘

샌드박스 사이트를 실행하여 Gato GraphQL을 체험해 보세요↗

👨🏻‍💻 GraphQL, 일종의 프로그래밍 언어로서

뉴스레터 구독하기