GraphQL

GraphQL은 클라이언트가 필요한 데이터의 모양을 직접 선언할 수 있게 하는 API 질의 언어이자 실행 방식입니다. 서버는 제공 가능한 데이터 타입과 관계를 스키마로 정의합니다.

query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

클라이언트는 사용자 이름과 게시글 제목만 요청했고, 서버는 그 모양에 맞춰 응답합니다.

REST에서는 화면 하나를 구성하기 위해 여러 Endpoint를 호출해야 할 수 있습니다.

GET /users/1
GET /users/1/posts
GET /posts/최근글/comments

또는 응답에 필요하지 않은 데이터까지 포함되는 Over-fetching, 반대로 필요한 데이터가 부족해 추가 요청이 필요한 Under-fetching이 생길 수 있습니다. GraphQL은 클라이언트가 필요한 필드를 선택하고 연관 데이터까지 한 질의로 요청할 수 있게 합니다.

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

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

type Query {
  user(id: ID!): User
}

• type: 데이터의 구조
• ID!: null이 될 수 없는 ID
• [Post!]!: 목록과 목록의 각 항목이 null이 아님
• Query: 조회할 수 있는 진입점

스키마는 문서이자 클라이언트와 서버 사이의 계약입니다. 타입을 기반으로 자동 완성, 검증, 코드 생성 도구를 활용할 수 있습니다.

GraphQL에서는 서버의 기능을 크게 세 가지 형태로 구분합니다.

Query
→ 데이터 조회

Mutation
→ 데이터 생성·수정·삭제

Subscription
→ 데이터 변경을 실시간으로 전달받기

REST API와 비교하면 다음과 비슷하게 이해할 수 있습니다.

단, GraphQL과 REST는 구조가 달라서 완전히 같은 개념은 아니고, 위 표는 역할을 대략 비교한 것입니다.

4.1 Query

Query는 서버의 데이터를 조회할 때 사용합니다.

쉽게 말하면 서버에 다음과 같이 질문하는 것입니다.

1번 사용자의 이름과 이메일을 알려주세요.

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

서버는 클라이언트가 요청한 필드만 반환합니다.

{
  "data": {
    "user": {
      "name": "홍길동",
      "email": "hong@example.com"
    }
  }
}

이름만 필요하다면 name만 요청할 수도 있습니다.

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

응답에도 이름만 포함됩니다.

Resolver는 GraphQL 스키마에 정의된 필드의 실제 데이터를 가져오거나 작업을 실행하는 함수입니다.

user(id: 1)
→ User Resolver가 사용자 조회

posts 필드
→ Post Resolver가 게시글 조회

예를 들어 다음 Query가 들어오면:

query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

서버는 사용자를 조회하는 Resolver와 해당 사용자의 게시글을 조회하는 Resolver를 순서대로 실행합니다.

Resolver를 사용하면 클라이언트가 요청한 필드에 맞춰 필요한 데이터를 조회할 수 있습니다. 하지만 목록에 포함된 관계 데이터를 각 Resolver가 개별적으로 조회하면 같은 형태의 DB Query가 반복되는 N+1 문제가 발생할 수 있습니다.

이 문제는 DataLoader를 이용한 일괄 조회, JOIN, ORM 관계 조회, 페이지네이션 등의 방법으로 해결할 수 있습니다.

{
  "data": {
    "user": {
      "name": "홍길동"
    }
  },
  "errors": []
}

일부 필드에서 오류가 발생해도 성공한 데이터와 오류 정보가 함께 올 수 있습니다. 또한 HTTP 자체는 200 OK인데 GraphQL 응답의 errors에 업무 오류가 담기는 설계도 가능하므로, 클라이언트는 HTTP 상태 코드와 GraphQL 오류 구조를 모두 이해해야 합니다.

장점

• 화면에 필요한 필드만 요청할 수 있습니다.
• 연관 데이터를 하나의 질의로 표현할 수 있습니다.
• 강한 타입과 스키마 기반 도구를 활용할 수 있습니다.
• 여러 종류의 클라이언트가 각자 다른 데이터 모양을 요구할 때 유연합니다.

한계

• 서버의 실행과 성능 최적화가 복잡해질 수 있습니다.
• HTTP URL 단위의 기본 캐시를 그대로 활용하기 어렵습니다.
• 클라이언트가 지나치게 복잡하거나 비싼 질의를 보낼 수 있어 깊이·복잡도 제한이 필요합니다.
• 파일 업로드, 오류 정책, 권한 검사를 팀 규칙으로 잘 정해야 합니다.

반드시 그렇지는 않습니다. 단순 CRUD 서비스라면 REST가 더 이해하고 운영하기 쉬울 수 있습니다. 반대로 여러 화면과 클라이언트가 복잡한 관계 데이터를 각기 다른 모양으로 요구한다면 GraphQL의 장점이 커집니다.

한 서비스에서 외부 API는 REST, 프론트엔드 전용 집계 API는 GraphQL처럼 병행할 수도 있습니다.

• 웹·모바일 등 클라이언트별 데이터 요구가 크게 다름
• 하나의 화면이 여러 연관 자원을 조합함
• API 변경 요청이 빈번하고 스키마 기반 협업이 중요함
• GraphQL 운영 복잡성을 감당할 팀과 도구가 있음

GraphQL은 서버가 제공하는 타입과 관계 안에서 클라이언트가 필요한 데이터의 모양을 선언하는 API 방식이다.