이 글은 GraphQL Docs를 읽고 정리한 글입니다.

스키마

타입 시스템

• GraphQL 쿼리의 형태가 결과와 거의 일치하기 때문에 클라이언트는 서버에 대해 알지 못해도 결과를 예측할 수 있다.
• 그런데 이 때, 선택할 수 있는 필드가 무엇인지/ 객체의 종류는 무엇인지/ 하위 객체에서 사용 가능한 필드가 무엇인지 알기 위해서는 스키마가 필요하다.

모든 GraphQL 서비스는 쿼리가 들어오면 해당 스키마에 대한 유효성 검사 후 실행 되는 과정을 거친다.

객체 타입과 필드

GraphQL 스키마의 기본 구성 요소는 객체 타입이다.

type Character {
  name: String!
  appearsIn: [Episode]!
}

• Character: 객체 타입
• name, appearIn: Character 타입의 필드
• String: 내장된 스칼라 타입으로 쿼리에서 하위 선택을 할 수 없다.
• [Episode]: Episode 객체의 배열(array)

인자

type Starship {
  id: ID!
  name: String!
  length(unit: LengthUnit = METER): Float
}

• GraphQL 객체 타입의 모든 필드는 인자를 가질 수 있다.
• length에 전달되는 인자 unit의 타입은 LengthUnit이며 기본 값은 METER이다.

타입

Docs에서는 여러 종류의 타입을 나열했는데 여기에는 생소한 타입을 중점적으로 정리했다.

쿼리 타입 & 뮤테이션 타입

• 스키마 대부분은 일반 객체 타입이지만 스키마 내에는 query, mutation이라는 특수한 타입 두 가지를 가진다.
• 이 두 가지 타입은 GraphQL 쿼리의 진입점(entry point)을 정의한다.

아래와 같이 쿼리하기 위해서는

쿼리

query {
  hero {
    name
  }
  droid(id: "2000") {
    name
  }
}

아래와 같이 hero, droid 필드를 가진 Query 타입이 정의되어 있어야 한다.

GraphQL 서비스

type Query {
  hero(episode: Episode): Character
  droid(id: ID!): Droid
}

위의 예시는 Query 타입에 대한 것이지만 Mutation 타입도 유사한 방식으로 작동한다.

열거형 타입

• Enums라고도 한다.
• 열거형 타입은 특정 값들로 제한되는 특별한 종류의 스칼라이다.
• 열거형 타입의 특징
  - 타입의 인자가 허용된 값 중 하나임을 검증한다.
  - 필드가 항상 값의 열거형 집합 중 하나가 될 것임을 타입 시스템을 통해 의사소통 한다.

아래의 예시를 보면 스키마에서 Episode 타입을 사용할 경우 인자가 NEWHOPE, EMPIRE, JEDI 중 하나가 된다는 것을 알 수 있다.

쿼리

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

인터페이스

• 인터페이스는 이를 구현하기 위해 타입이 포함해야 하는 특정 필드들을 포함하는 추상 타입이다.

• 아래의 경우를 예로 들면, Character 인터페이스는 이를 구현한 모든 타입은 아래와 같은 인자와 리턴 타입을 가진 필드를 포함해야 한다는 의미가 된다.

  interface Character {
    id: ID!
    name: String!
    friends: [Character]
    appearsIn: [Episode]!
  }

• 아래와 같이 두 타입을 생성할 경우 두 타입은 모두 Character 인터페이스의 모든 필드를 가져야 하며 특정 타입의 경우 추가 필드를 가질 수 있다.

  type Human implements Character {
    id: ID!
    name: String!
    friends: [Character]
    appearsIn: [Episode]!
    starships: [Starship]
    totalCredits: Int
  }
  
  type Droid implements Character {
    id: ID!
    name: String!
    friends: [Character]
    appearsIn: [Episode]!
    primaryFunction: String
  }

유니온 타입

• 인터페이스와 유사하지만 타입 간 공통 필드를 갖지 않는다.
• 유니온 타입이 갖는 타입은 다른 유니온 타입이 될 수 없다.
  - 구체적인 객체 타입이어야 한다.
• 아래와 같은 유니온 타입의 경우, SearchResult 타입을 반환할 때마다 Human, Droid, Starship을 얻을 수 있다.

	union SearchResult = Human | Droid | Starship

입력 타입

• 복잡한 객체도 인자로 쉽게 전달할 수 있다.
• 이는 뮤테이션에서 유용하다.
• GraphQL 스키마 언어에서는 입력 타입에 대해 input을 사용한다.

  input ReviewInput {
    stars: Int!
    commentary: String
  }

쿼리

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

// variables
{
  "ep": "JEDI",
  "review": {
    "stars": 5,
    "commentary": "This is a great movie!"
  }
}

실행 결과

{
  "data": {
    "createReview": {
      "stars": 5,
      "commentary": "This is a great movie!"
    }
  }
}