GraphQL 기초부터 심화까지 완벽 가이드

GraphQL의 핵심 개념부터 고급 패턴까지 실전 예제로 배웁니다. Query, Mutation, Subscription, 성능 최적화까지 모든 것을 다룹니다.

---

---

들어가며

이 글에서는 GraphQL 기초부터 심화까지 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. 기본_스키마_정의
2. Query_정의
3. Mutation_정의
4. Resolver_구현
5. Input_Type_활용
6. Fragment_활용
7. DataLoader_패턴
8. Subscription_구현
9. Union_Type
10. Interface_활용
11. Directive_사용
12. Error_Handling

---

1. 기본 스키마 정의

개요

GraphQL 스키마는 타입 시스템으로 API 구조를 정의합니다. 쿼리 가능한 데이터와 관계를 명시합니다.

코드 예제

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

설명

User와 Post 타입을 정의하고 느낌표(!)로 필수 필드를 표시합니다. 배열은 대괄호로 표현합니다.

---

2. Query 정의

개요

Query는 데이터를 조회하는 진입점입니다. REST의 GET과 유사한 역할을 합니다.

코드 예제

type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
  post(id: ID!): Post
  posts(authorId: ID): [Post!]!
}

설명

단일 객체 조회와 리스트 조회를 정의하며, 기본값 설정도 가능합니다.

---

3. Mutation 정의

개요

Mutation은 데이터를 생성, 수정, 삭제하는 작업을 정의합니다. REST의 POST, PUT, DELETE와 유사합니다.

코드 예제

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
  deleteUser(id: ID!): Boolean!
  createPost(title: String!, authorId: ID!): Post!
}

설명

각 Mutation은 입력 파라미터와 반환 타입을 명확히 정의합니다.

---

4. Resolver 구현

개요

Resolver는 스키마의 각 필드에 대한 실제 데이터를 반환하는 함수입니다.

코드 예제

const resolvers = {
  Query: {
    user: (_, { id }, { db }) => db.users.find(u => u.id === id),
    users: (_, { limit }, { db }) => db.users.slice(0, limit)
  },
  User: {
    posts: (user, _, { db }) => db.posts.filter(p => p.authorId === user.id)
  }
}

설명

parent, args, context 인자를 활용해 데이터를 조회하고 반환합니다.

---

5. Input Type 활용

개요

복잡한 입력 데이터를 재사용 가능한 Input 타입으로 정의할 수 있습니다.

코드 예제

input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

설명

Input 타입으로 여러 필드를 그룹화하여 코드의 재사용성을 높입니다.

---

6. Fragment 활용

개요

Fragment는 재사용 가능한 필드 집합을 정의하여 쿼리를 간결하게 만듭니다.

코드 예제

fragment UserInfo on User {
  id
  name
  email
}

query GetUsers {
  users {
    ...UserInfo
    posts { title }
  }
}

설명

공통으로 사용되는 필드를 Fragment로 정의하고 ...으로 재사용합니다.

---

7. DataLoader 패턴

개요

N+1 쿼리 문제를 해결하는 배치 로딩 패턴입니다. 여러 요청을 모아서 한 번에 처리합니다.

코드 예제

const userLoader = new DataLoader(async (ids) => {
  const users = await db.users.findMany({ where: { id: { in: ids } } });
  return ids.map(id => users.find(u => u.id === id));
});

const resolvers = {
  Post: { author: (post) => userLoader.load(post.authorId) }
}

설명

DataLoader가 요청을 모아서 일괄 처리하여 데이터베이스 쿼리 수를 최적화합니다.

---

8. Subscription 구현

개요

Subscription은 실시간 데이터 업데이트를 위한 WebSocket 기반 통신입니다.

코드 예제

type Subscription {
  postAdded: Post!
  userUpdated(id: ID!): User!
}

const resolvers = {
  Subscription: {
    postAdded: { subscribe: () => pubsub.asyncIterator(['POST_ADDED']) }
  }
}

설명

PubSub 패턴으로 이벤트를 구독하고 실시간으로 클라이언트에 전달합니다.

---

9. Union Type

개요

Union 타입은 여러 타입 중 하나를 반환할 수 있는 유연한 타입입니다.

코드 예제

type Image { url: String! }
type Video { url: String!, duration: Int! }

union Media = Image | Video

type Post {
  id: ID!
  content: Media!
}

설명

하나의 필드가 여러 타입을 가질 수 있어 다형성을 구현할 수 있습니다.

---

10. Interface 활용

개요

Interface는 공통 필드를 가진 타입들의 추상화를 제공합니다.

코드 예제

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

설명

여러 타입이 공통 인터페이스를 구현하여 일관된 API 설계가 가능합니다.

---

11. Directive 사용

개요

Directive는 쿼리나 스키마에 동적 로직을 추가하는 메타데이터입니다.

코드 예제

query GetUser($withPosts: Boolean!) {
  user(id: "1") {
    id
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

설명

@include, @skip 등의 directive로 조건부 필드 조회가 가능합니다.

---

12. Error Handling

개요

GraphQL에서 에러를 구조화하여 클라이언트에 명확한 정보를 전달합니다.

코드 예제

import { GraphQLError } from 'graphql';

const resolvers = {
  Query: {
    user: (_, { id }, { db }) => {
      const user = db.users.find(u => u.id === id);
      if (!user) throw new GraphQLError('User not found', {
        extensions: { code: 'NOT_FOUND' }
      });
      return user;
    }
  }
}

설명

GraphQLError를 사용해 에러 코드와 메시지를 구조화하여 클라이언트 처리를 용이하게 합니다.

---

마치며

이번 글에서는 GraphQL 기초부터 심화까지 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#GraphQL #Schema #Resolver #Mutation #DataLoader