프론트엔드 개발자를 위한 GraphQL 입문

들어가며

안녕하세요. 노머스 프론트엔드 팀의 하수빈입니다.

프론트엔드 개발자로서 다양한 작업을 수행하지만, 그중에서도 서버와의 통신은 매우 중요한 업무입니다. 현재 저희 노머스에서도 일부 서비스에 GraphQL을 도입하는 것을 검토 중입니다. 이에 발맞추어 GraphQL에 대해 빠르게 알아보고자 합니다.

GraphQL이란?

GraphQL은 Facebook에서 개발한 오픈 소스 데이터 쿼리 언어입니다. 클라이언트가 필요한 데이터를 정확하게 요청할 수 있도록 하여 네트워크 효율성을 극대화하고, 단일 엔드포인트를 통해 다양한 데이터 요청을 처리할 수 있는 유연성을 제공합니다. 이를 통해 프론트엔드 개발자들은 보다 간편하고 효율적으로 데이터를 관리할 수 있습니다.

GraphQL 쿼리 언어란?

GraphQL 쿼리 언어는 클라이언트가 필요한 데이터를 구조화된 방식으로 요청할 수 있도록 합니다. 이는 클라이언트가 서버로부터 정확히 어떤 데이터를 필요로 하는지 명시할 수 있어, 불필요한 데이터 전송을 줄이고 응답 시간을 최적화할 수 있습니다.

간단한 예시

예를 들어, 사용자의 이름과 이메일을 요청하는 GraphQL 쿼리는 다음과 같습니다:

query {
  user(id: 1) {
    name
    email
  }
}

위 쿼리는 user 엔티티에서 id가 1인 사용자의 name과 email 필드를 요청합니다. 서버는 이 요청에 따라 정확히 해당 필드만 포함된 데이터를 반환합니다.

응답 예시

서버는 클라이언트의 요청에 따라 JSON 형식의 데이터를 반환합니다. 예를 들어, 위의 쿼리에 대한 응답은 다음과 같습니다:

{
  "data": {
    "user": {
      "name": "Luke Skywalker",
      "email": "luke@rebellion.com"
    }
  }
}

이 응답은 클라이언트가 요청한 데이터 구조에 맞추어 반환됩니다. data 객체 내에 user 객체가 포함되어 있으며, 요청한 name과 email 필드가 제공됩니다. 이를 통해 클라이언트는 필요한 데이터만 정확히 받아볼 수 있습니다.

REST API와의 차이점

GraphQL과 REST API는 모두 서버와 클라이언트 간의 데이터 통신을 위해 사용되지만, 몇 가지 중요한 차이점이 있습니다:

1. 데이터 요청 방식

• REST API: 각 리소스에 대해 고유한 URL을 가지고 있으며, 특정 엔드포인트에서 데이터를 가져옵니다. 예를 들어, /users 엔드포인트는 사용자 데이터를 반환하고, /posts 엔드포인트는 게시물 데이터를 반환합니다.
• GraphQL: 단일 엔드포인트(/graphql)를 통해 클라이언트가 필요한 데이터를 쿼리합니다. 클라이언트는 요청 시 필요한 필드만 명시하여 데이터를 가져올 수 있습니다.

2. 오버 페칭 및 언더 페칭

• REST API: 특정 엔드포인트에서 불필요한 데이터를 포함한 오버 페칭(over-fetching)이나 필요한 데이터가 부족한 언더 페칭(under-fetching)이 발생할 수 있습니다. 예를 들어, /users 엔드포인트가 모든 사용자 정보를 반환할 때, 클라이언트는 특정 사용자 필드만 필요로 하더라도 전체 데이터를 받아야 합니다.
• GraphQL: 클라이언트가 필요한 데이터만 요청할 수 있어 오버 페칭과 언더 페칭 문제를 해결합니다. 예를 들어, 사용자 이름과 이메일만 필요한 경우 해당 필드만 요청할 수 있습니다.

3. 버전 관리

• REST API: 엔드포인트 버전 관리가 필요합니다. 새로운 기능이나 데이터 구조 변경 시, /v1/users, /v2/users와 같은 엔드포인트 버전 관리가 필요합니다.
• GraphQL: 버전 관리가 필요 없습니다. 클라이언트가 요청하는 데이터 구조를 정의할 수 있으므로, 서버 측에서 데이터 구조 변경이 발생하더라도 클라이언트는 영향을 받지 않습니다.

4. 네트워크 요청 수

• REST API: 여러 엔드포인트에서 데이터를 가져와야 하는 경우, 여러 번의 네트워크 요청이 필요합니다.
• GraphQL: 단일 쿼리로 여러 리소스를 동시에 요청할 수 있어 네트워크 요청 수를 줄일 수 있습니다.

REST API와 GraphQL의 차이점: Star Wars API 예시

샘플 REST API 서버
샘플 GraphQL API 서버

REST API와 GraphQL을 비교하기 위해 Star Wars API(SWAPI)를 사용한 예시를 살펴보겠습니다. SWAPI는 Star Wars 데이터에 접근할 수 있는 API입니다. 여기에서는 REST와 GraphQL을 통해 영화와 등장인물을 요청하는 예시를 통해 두 접근 방식의 차이점을 설명합니다.

REST API 예시

REST API를 사용하여 영화와 관련된 등장인물 데이터를 가져오려면 두 번의 요청이 필요합니다.

1. 영화 목록 가져오기

GET https://swapi.dev/api/films

응답 예시:

{
  "count": 6,
  "results": [
    {
      "title": "A New Hope",
      "episode_id": 4,
      "characters": [
        "https://swapi.dev/api/people/1/",
        "https://swapi.dev/api/people/2/"
      ]
    },
    ...
  ]
}

2. 영화에 등장하는 특정 인물 정보 가져오기

GET https://swapi.dev/api/people/1

응답 예시:

{
  "name": "Luke Skywalker",
  "height": "172",
  "mass": "77",
  "hair_color": "blond",
  "skin_color": "fair",
  "eye_color": "blue",
  "birth_year": "19BBY",
  "gender": "male"
}

이와 같은 방식으로 각 등장인물에 대해 별도의 요청이 필요합니다.

GraphQL 예시

GraphQL을 사용하면 단일 쿼리로 영화와 관련된 등장인물 데이터를 동시에 가져올 수 있습니다.

1. 단일 쿼리로 영화와 등장인물 데이터 요청

{
  allFilms {
    films {
      title
      episodeID
      characterConnection {
        characters {
          name
          height
          mass
          skinColor
        }
      }
    }
  }
}

응답 예시:

{
  "data": {
    "allFilms": {
      "films": [
        {
          "title": "A New Hope",
          "episodeID": 4,
          "characterConnection": {
            "characters": [
              {
                "name": "Luke Skywalker",
                "height": "172",
                "mass": "77",
                "skinColor": "fair"
              },
              ...
            ]
          }
        },
        ...
      ]
    }
  }
}

프론트엔드 적용하기

GraphQL을 프론트엔드 프로젝트에 도입하는 과정은 비교적 간단합니다. React를 예시로 설명하겠습니다.

1. Apollo Client 설치 및 설정

GraphQL 클라이언트로는 Apollo Client가 가장 많이 사용됩니다. Apollo Client를 사용하면 GraphQL 서버와 쉽게 통신할 수 있습니다.

설치

먼저, 프로젝트에 필요한 패키지를 설치합니다.

npm install @apollo/client graphql

설정

프로젝트의 최상위 컴포넌트에서 Apollo Client를 설정합니다. Apollo Client를 설정하고 이를 ApolloProvider로 감싸서 애플리케이션 전체에서 GraphQL 요청을 처리할 수 있도록 합니다.

import React from 'react';
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://your-graphql-endpoint.com/graphql',  // GraphQL 서버의 URI를 지정합니다.
  cache: new InMemoryCache()
});

function App() {
  return (
    <ApolloProvider client={client}>
      <YourComponent />
    </ApolloProvider>
  );
}

export default App;

2. GraphQL 쿼리 작성 및 데이터 요청

쿼리를 작성하고 데이터를 요청하는 방법은 다음과 같습니다.

쿼리 작성

GraphQL 쿼리를 작성합니다. gql 태그를 사용하여 쿼리를 정의합니다.

import { gql } from '@apollo/client';

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;

데이터 요청

React 컴포넌트에서 useQuery 훅을 사용하여 데이터를 요청합니다. useQuery 훅은 쿼리와 쿼리 변수(옵션)를 인수로 받아 데이터를 요청합니다.

import React from 'react';
import { useQuery } from '@apollo/client';
import { GET_USER } from './queries';

function UserComponent({ userId }) {
  const { loading, error, data } = useQuery(GET_USER, {
    variables: { id: userId }
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h1>{data.user.name}</h1>
      <p>{data.user.email}</p>
    </div>
  );
}

export default UserComponent;

useQuery 훅은 loading, error, data를 반환하며, 이를 통해 로딩 상태, 에러 상태, 그리고 데이터를 쉽게 관리할 수 있습니다.

3. GraphQL을 활용한 고급 기능

GraphQL을 활용한 고급 기능에는 뮤테이션, 캐싱, 서브스크립션이 포함됩니다. 이를 통해 데이터 변경, 성능 최적화, 실시간 업데이트를 쉽게 구현할 수 있습니다.

뮤테이션 (Mutation)

데이터를 변경하는 요청(예: 생성, 수정, 삭제)은 useMutation 훅을 사용합니다. 예를 들어, 새로운 사용자를 생성하는 뮤테이션은 다음과 같이 작성할 수 있습니다.

import { gql, useMutation } from '@apollo/client';

const CREATE_USER = gql`
  mutation CreateUser($name: String!, $email: String!) {
    createUser(name: $name, email: $email) {
      id
      name
      email
    }
  }
`;

function CreateUserComponent() {
  let inputName, inputEmail;
  const [createUser, { data }] = useMutation(CREATE_USER);

  return (
    <div>
      <form
        onSubmit={e => {
          e.preventDefault();
          createUser({ variables: { name: inputName.value, email: inputEmail.value } });
          inputName.value = '';
          inputEmail.value = '';
        }}
      >
        <input
          ref={node => {
            inputName = node;
          }}
          type="text"
          placeholder="Name"
        />
        <input
          ref={node => {
            inputEmail = node;
          }}
          type="email"
          placeholder="Email"
        />
        <button type="submit">Create User</button>
      </form>
    </div>
  );
}

export default CreateUserComponent;

캐싱

Apollo Client는 InMemoryCache를 사용하여 요청된 데이터를 캐싱합니다. 이를 통해 동일한 데이터를 여러 번 요청하는 것을 방지하고 애플리케이션의 성능을 향상시킬 수 있습니다.

서브스크립션 (Subscription)

실시간 데이터 업데이트가 필요한 경우 useSubscription 훅을 사용하여 GraphQL 서브스크립션을 처리할 수 있습니다. 이를 통해 서버로부터 실시간 업데이트를 받을 수 있습니다.

import { gql, useSubscription } from '@apollo/client';

const USER_ADDED = gql`
  subscription OnUserAdded {
    userAdded {
      id
      name
      email
    }
  }
`;

function NewUsersComponent() {
  const { data, loading } = useSubscription(USER_ADDED);

  if (loading) return <p>Loading...</p>;

  return (
    <div>
      <p>New user added:</p>
      <p>Name: {data.userAdded.name}</p>
      <p>Email: {data.userAdded.email}</p>
    </div>
  );
}

export default NewUsersComponent;

결론

GraphQL 학습을 하면서 GraphQL은 프론트엔드 입장에서 개발하기 편한 통신 방식이라고 느껴졌습니다. 아직 프로덕션 레벨에서 사용해보지 못했지만, 앞으로 활용하게 되는 것에 기대감이 큽니다.

GraphQL의 장점과 단점을 살펴보면 다음과 같습니다.

장점

유연한 데이터 요청: GraphQL은 필요한 데이터만 요청할 수 있어 응답 사이즈를 최소화하고, 프론트엔드와 백엔드 간의 커플링을 줄입니다.

단일 엔드포인트 사용: GraphQL은 단일 엔드포인트로 다양한 데이터를 요청할 수 있어 여러 API 엔드포인트를 관리할 필요가 없습니다.

단점

학습 곡선: GraphQL의 개념과 사용법을 배우는 데 시간이 필요합니다. 특히, 기존 REST API에 익숙한 개발자에게는 새로운 패러다임에 적응하는 과정이 필요합니다.

복잡성 증가: 간단한 요청의 경우에도 쿼리와 뮤테이션을 작성해야 하므로 초기 설정과 구현에 시간이 더 걸릴 수 있습니다.

참고자료

짧은 글에 많은 내용을 담지 못했습니다. GraphQL 에 대해서 더 알고 싶다면 아래 자료들을 참고해주세요.

• https://tech.kakao.com/posts/364
• https://haesoo9410.tistory.com/345
• https://c17an.netlify.app/blog/front-end/graphql-만나보기-1편/article/
• https://velog.io/@hyunspace/about-GraphQL