Schemas and Types

이 페이지에서는 GraphQL 유형 시스템에 대해 알아야 할 사항과 쿼리 할 수 있는 데이터를 설명하는 방법을 배우게됩니다. GraphQL은 모든 백엔드 프레임 워크 또는 프로그래밍 언어와 함께 사용할 수 있기 때문에 구현 관련 세부 정보에서 벗어나 개념에 대해서만 이야기 할 것입니다. 

Type system

이전에 GraphQL 쿼리를 본 적이 있다면 GraphQL 쿼리 언어가 기본적으로 객체의 필드를 선택하는 것임을 알 수 있습니다. 예를 들어, 다음 쿼리에서: 

{ 

  hero { 

    name 

    appearsIn 

  } 

}

{

  "data": {

    "hero": {

      "name": "R2-D2",

      "appearsIn": [

        "NEWHOPE",

        "EMPIRE",

        "JEDI"

      ]

    }

  }

}

1. 특별한 "루트"객체로 시작합니다.
   
2. 우리는 그 영웅 필드를 선택합니다.
   
3. 영웅이 반환한 객체의 경우 이름과 표시 필드를 선택합니다.
   

모든 GraphQL 서비스는 해당 서비스에서 쿼리 할 수 있는 가능한 데이터 집합을 완전히 설명하는 유형 집합을 정의합니다. 그런 다음 쿼리가 들어 오면 해당 스키마에 대해 유효성이 검사되고 실행됩니다. 

Type language

GraphQL 서비스는 모든 언어로 작성할 수 있습니다. GraphQL 스키마에 대해 이야기하기 위해 JavaScript와 같은 특정 프로그래밍 언어 구문에 의존 할 수 없기 때문에 우리는 우리 자신의 간단한 언어를 정의 할 것입니다. 우리는 "GraphQL 스키마 언어"를 사용할 것입니다 - 이것은 쿼리 언어와 비슷하며 Graphicality 스키마를 언어에 구애받지 않는 방식으로 이야기 할 수있게 해줍니다. 

Object types and fields

GraphQL 스키마의 가장 기본적인 구성 요소는 객체 유형입니다. 객체 유형은 서비스에서 가져올 수있는 객체의 종류와 필드가있는 필드를 나타냅니다. GraphQL 스키마 언어에서는 다음과 같이 표현할 수 있습니다. 

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

언어는 꽤 읽을 만하지만, 우리가 공유 어휘를 가질 수 있도록 그 언어를 살펴 보겠습니다. 

• Character는 GraphQL Object Type으로 일부 필드가 있는 유형입니다. 스키마의 대부분의 유형은 객체 유형입니다.
  
• name 및 appearIn은 문자 유형의 필드입니다. 즉, Name 및 appearIn은 Character 유형에서 작동하는 GraphQL 쿼리의 모든 부분에 나타날 수있는 유일한 필드입니다.
  
• String은 기본 제공 스칼라 유형 중 하나입니다. 이러한 유형은 단일 스칼라 객체로 해석되는 유형이며 쿼리에서 하위 선택을 가질 수 없습니다. 우리는 스칼라 유형을 나중에 처리 할 것입니다.
  
• String! 필드가 nullable이 아니라는 것을 의미합니다. 즉,이 필드를 쿼리 할 때 GraphQL 서비스가 항상 값을 제공한다는 것을 의미합니다. 형식 언어에서는 느낌표가 있는 문자를 나타냅니다.
  
• [Episode]! 에피소드 개체의 배열을 나타냅니다. 또한 nullable이 아니기 때문에 appearIn 필드를 쿼리 할 때 항상 0 이상의 항목이있는 배열을 기대할 수 있습니다.
  

이제 GraphQL 객체 유형이 무엇인지 알 수 있으며 GraphQL 유형 언어의 기본 사항을 읽는 방법을 알 수 있습니다. 

Arguments

GraphQL 객체 유형의 모든 필드는 0 개 이상의 인수를 가질 수 있습니다 (예 : 아래의 길이 필드). 

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

모든 인수의 이름이 지정됩니다. 함수가 정렬된 인수 목록을 가져 오는 JavaScript 및 Python과 같은 언어와 달리 GraphQL의 모든 인수는 특별히 이름으로 전달됩니다. 이 경우 길이 필드에는 하나의 정의 된 인수 unit이 있습니다. 

인수는 필수 또는 선택적일 수 있습니다. 인수가 선택적이면 기본값을 정의 할 수 있습니다. 단위 인수가 전달되지 않으면 기본적으로 METER로 설정됩니다. 

The Query and Mutation types

스키마의 대부분의 유형은 일반 오브젝트 유형일 뿐이지만 스키마 내에서 특수한 두 가지 유형이 있습니다. 

schema {
  query: Query
  mutation: Mutation
}

모든 GraphQL 서비스는 질의 유형을 가지며 뮤테이션 유형을 가질 수도 그렇지 않을 수도 있습니다. 이러한 유형은 일반 객체 유형과 동일하지만 모든 GraphQL 질의의 진입점을 정의하기 때문에 특별합니다. 따라서 다음과 같은 쿼리를 볼 수 있습니다.

query {

  hero {

    name

  }

  droid(id: "2000") {

    name

  }

}

{

  "data": {

    "hero": {

      "name": "R2-D2"

    },

    "droid": {

      "name": "C-3PO"

    }

  }

}

즉, GraphQL 서비스에는 영웅 및 드로이드 필드가 있는 쿼리 유형이 있어야합니다. 

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

Mutation은 비슷한 방식으로 작동합니다. 즉, Mutation 유형의 필드를 정의하면 쿼리에서 호출할 수 있는 루트 변형 필드로 사용할 수 있습니다. 

스키마에 대한 "진입점"이 되는 특별한 상태 이외의 쿼리 및 변형 유형은 다른 GraphQL 객체 유형과 동일하며 해당 필드는 정확히 동일한 방식으로 작동한다는 점을 기억해야합니다. 

Scalar types

GraphQL 객체 유형은 이름과 필드를 가지고 있지만, 어느 시점에서 그 필드는 어떤 구체적인 데이터로 해석되어야 합니다. 그것은 스칼라 유형이 들어오는 곳입니다. 즉, 스칼라 유형이 쿼리의 나뭇잎(the leaves of the query)을 나타냅니다. 

다음 쿼리에서 이름과 appearIn은 스칼라 유형을 확인합니다. 

{

  hero {

    name

    appearsIn

  }

}

{

  "data": {

    "hero": {

      "name": "R2-D2",

      "appearsIn": [

        "NEWHOPE",

        "EMPIRE",

        "JEDI"

      ]

    }

  }

}

이러한 필드는 서브 필드가 없기 때문에 이를 알 수 있습니다. 서브 필드는 쿼리의 나뭇잎입니다. 

GraphQL에는 기본 스칼라 유형 세트가 기본 제공됩니다. 

• Int: 부호있는 32 비트 정수입니다.
  
• Float: 부호있는 배정 밀도 부동 소수점 값.
  
• String: UTF-8 문자 시퀀스입니다.
  
• Boolean: true 또는 false입니다.
  
• ID: ID 스칼라 유형은 객체를 다시 페치하거나 캐시의 키로 자주 사용되는 고유 식별자를 나타냅니다. ID 형은 String와 같은 방법으로 직렬화됩니다. 그러나 이를 ID로 정의하는 것은 사람이 읽을 수 있는 의도가 아니라는 것을 의미합니다.
  

대부분의 GraphQL 서비스 구현에는 맞춤 스칼라 유형을 지정하는 방법이 있습니다. 예를 들어 Date 유형을 정의 할 수 있습니다. 

scalar Date

그런 다음 해당 유형을 직렬화, 역 직렬화 및 유효성 검사를 수행하는 방법을 정의하는 것은 구현에 달려 있습니다. 예를 들어 Date 유형을 항상 정수형 시간 소인으로 직렬화해야 하며 클라이언트는 모든 날짜 필드에 대해 해당 형식을 사용해야 한다는 것을 알아야합니다. 

Enumeration types

열거형이라고도 하는 열거형은 허용되는 특정 값 집합으로 제한되는 특별한 종류의 스칼라입니다. 이를 통해 다음을 수행 할 수 있습니다. 

1. 이 유형의 인수가 허용된 값 중 하나임을 확인합니다.
   
2. 필드가 항상 값의 유한 집합중 하나가 될 것임을 타입 시스템을 통해 전달하십시오.
   

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

즉, 스키마에서 Episode 유형을 사용하는 곳에서는 NEWHOPE, EMPIRE 또는 JEDI 중 하나 일 것으로 예상됩니다. 

다양한 언어로 구현 된 GraphQL 서비스는 열거형을 처리 할 수 있는 언어별 방법을 제공합니다. enum을 일류 시민으로 지원하는 언어에서는 구현시 이를 활용할 수 있습니다. 열거형 지원이 없는 JavaScript와 같은 언어에서 이 값은 내부적으로 정수 집합에 매핑 될 수 있습니다. 그러나 이러한 세부 정보는 클라이언트로 누출되지 않으며 열거형 값의 문자열 이름 측면에서 완전히 작동 할 수 있습니다. 

Lists and Non-Null

객체 유형, 스칼라 및 열거형은 GraphQL에서 정의 할 수 있는 유일한 유형입니다. 그러나 스키마의 다른 부분이나 쿼리 변수 선언에서 유형을 사용하면 해당 값의 유효성 검사에 영향을 주는 추가 유형 수정자를 적용 할 수 있습니다. 예제를 살펴 보겠습니다. 

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

여기서는 형식 이름 다음에 느낌표(!)를 추가하여 String 유형을 Non-Null로 표시합니다. 즉, 우리 서버는 항상이 필드에 대해 null이 아닌 값을 반환 할 것으로 예상하고 실제로 GraphQL 실행 오류를 발생시키는 null 값을 얻으면 결국 클라이언트에게 문제가 있음을 알립니다. 

Non-Null 유형 수정자는 필드에 대한 인수를 정의할 때도 사용할 수 있습니다. 이는 GraphQL 서버가 GraphQL 문자열이나 변수에 상관없이 null 값이 해당 인수로 전달되면 유효성 검사 오류를 반환하게 합니다. 

query DroidById($id: ID!) {

  droid(id: $id) {

    name

  }

}

variables

{

  "id": null

}

results

{

  "errors": [

    {

      "message": "Variable \"$id\" of required type \"ID!\" was not provided.",

      "locations": [

        {

          "line": 1,

          "column": 17

        }

      ]

    }

  ]

}

목록(List)은 비슷한 방식으로 작동합니다. 유형 수정자를 사용하여 유형을 List로 표시 할 수 있습니다.이 필드는 해당 유형의 배열을 반환합니다. 스키마 언어에서, 이것은 대괄호[]로 유형을 래핑하여 표시됩니다. 유효성 검사 단계에서 해당 값에 대한 배열이 필요한 인수에 대해서도 동일하게 작동합니다. 

그는 Non-Null과 List 수식어를 결합할 수 있습니다. 예를 들어 Null이 아닌 문자열 목록을 가질 수 있습니다. 

myField: [String!]

즉, 목록 자체는 null 일 수 있지만 null 멤버는 가질 수 없습니다. 예를 들어, JSON: 

myField: null // valid
myField: ['a', 'b'] // valid
myField: ['a', null, 'b'] // error

이제 Null이 아닌 문자열 목록을 정의했다고 가정 해 봅니다. 

myField: [String]!

즉, 목록 자체는 null 일 수는 없지만 null 값을 포함 할 수 있습니다. 

myField: null // error
myField: ['a', 'b'] // valid
myField: ['a', null, 'b'] // valid

필요에 따라 임의의 수의 Null 및 List 한정자를 임의로 중첩할 수 있습니다.