Schemas and Types
이 페이지에서는 GraphQL 유형 시스템과 쿼리할 수 있는 데이터를 설명하는 방법에 대해 알아야 할 모든 것을 배울 것입니다. GraphQL은 모든 백엔드 프레임워크 또는 프로그래밍 언어와 함께 사용할 수 있으므로 구현 관련 세부 사항은 피하고 개념에 대해서만 이야기하겠습니다.1)
Type System
이전에 GraphQL 쿼리를 본 적이 있다면 GraphQL 쿼리 언어가 기본적으로 개체의 필드를 선택하는 것에 관한 것임을 알고 있습니다. 예를 들어 다음 쿼리에서:2)
{
hero {
name
appearsIn
}
}
{
"data": {
"hero": {
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
}
}
GraphQL 쿼리의 모양은 결과와 거의 일치하기 때문에 서버에 대해 많이 알지 않고도 쿼리가 반환할 내용을 예측할 수 있습니다. 그러나 우리가 요청할 수 있는 데이터에 대한 정확한 설명을 갖는 것이 유용합니다. 어떤 필드를 선택할 수 있습니까? 그들은 어떤 종류의 물건을 반환할 수 있습니까? 해당 하위 개체에서 사용할 수 있는 필드는 무엇입니까? 바로 여기에서 스키마가 등장합니다.6)
모든 GraphQL 서비스는 해당 서비스에서 쿼리할 수 있는 가능한 데이터 집합을 완전히 설명하는 유형 집합을 정의합니다. 그런 다음 쿼리가 들어오면 해당 스키마에 대해 유효성이 검사되고 실행됩니다.7)
Type Language
GraphQL 서비스는 모든 언어로 작성할 수 있습니다. GraphQL 스키마에 대해 이야기하기 위해 JavaScript와 같은 특정 프로그래밍 언어 구문에 의존할 수 없기 때문에 우리만의 간단한 언어를 정의하겠습니다. “GraphQL 스키마 언어”를 사용하겠습니다. 쿼리 언어와 유사하며 언어에 구애받지 않는 방식으로 GraphQL 스키마에 대해 이야기할 수 있습니다.8)
Object Types and Fields
GraphQL 스키마의 가장 기본적인 구성 요소는 서비스에서 가져올 수 있는 개체의 종류와 포함하는 필드를 나타내는 개체 유형입니다. GraphQL 스키마 언어에서는 다음과 같이 나타낼 수 있습니다.9)
type Character {
name: String!
appearsIn: [Episode!]!
}
언어는 꽤 읽기 쉽지만 공유 어휘를 가질 수 있도록 살펴 보겠습니다.10)
- String!은 필드가 non-nullable임을 의미합니다. 즉, GraphQL 서비스는 이 필드를 쿼리할 때 항상 값을 제공할 것을 약속합니다. type language에서는 느낌표로 표시합니다.14)
- [Episode!]!은 Episode객체의 배열을 나타냅니다. Episode 또한 non-nullable이므로 appearsIn 필드를 쿼리할 때 항상 배열(0개 이상의 항목 포함)을 기대할 수 있습니다. 또한 Episode!은 non-nullable이므로 항상 배열의 모든 항목이 Episode 개체일 것으로 예상할 수 있습니다.
이제 GraphQL 객체 유형이 어떻게 생겼는지, GraphQL 유형 언어의 기본 사항을 읽는 방법을 알게 되었습니다.15)
Arguments
GraphQL 객체 유형의 모든 필드는 0개 이상의 인수를 가질 수 있습니다(예, 아래의 length 필드)16)
type Starship {
id: ID!
name: String!
length(unit: LengthUnit = METER): Float
}
모든 인수의 이름이 지정됩니다. 함수가 순서가 지정된 인수 목록을 취하는 JavaScript 및 Python과 같은 언어와 달리 GraphQL의 모든 인수는 구체적으로 이름으로 전달됩니다. 이 경우 length 필드에는 정의된 하나의 unit 인수가 있습니다.17)
The Query and Mutation Types
스키마의 대부분의 유형은 일반 객체 유형이지만 스키마 내에는 특별한 두 가지 유형이 있습니다.
schema {
query: Query
mutation: Mutation
}
모든 GraphQL 서비스에는 query유형이 있으며 mutation유형이 있을 수도 있고 없을 수도 있습니다. 이러한 유형은 일반 개체 유형과 동일하지만, 모든 GraphQL 쿼리의 진입점을 정의하기 때문에 특별합니다. 따라서 다음과 같은 쿼리가 표시되면
query {
hero {
name
}
droid(id: "2000") {
name
}
}
{
"data": {
"hero": {
"name": "R2-D2"
},
"droid": {
"name": "C-3PO"
}
}
}
즉, GraphQL 서비스에는 hero 및 droid 필드가 있는 Query 유형이 있어야 합니다.18)
type Query {
hero(episode: Episode): Character
droid(id: ID!): Droid
}
Mutations 은 유사한 방식으로 작동합니다. Mutation유형에 필드를 정의하면 쿼리에서 호출할 수 있는 root mutation 필드로 사용할 수 있습니다.19)
스키마에 대한 “진입점”이라는 특수한 상태를 제외하고 Query및 Mutation유형은 다른 GraphQL 객체 유형과 동일하며 해당 필드는 정확히 동일한 방식으로 작동한다는 점을 기억하는 것이 중요합니다.20)
Scala Types
GraphQL 객체 유형에는 이름과 필드가 있지만 어느 시점에서 이러한 필드는 구체적인 데이터로 해석되어야 합니다. 그것이 스칼라 유형이 들어오는 곳입니다. 그들은 쿼리의 잎을 나타냅니다.21)
다음 쿼리에서 name 및 appearsIn 필드는 스칼라 유형으로 확인됩니다.
{
hero {
name
appearsIn
}
}
{
"data": {
"hero": {
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
}
}
이러한 필드에는 하위 필드가 없기 때문에 이를 알 수 있습니다. 이는 쿼리의 잎사귀이기 때문입니다.22)
GraphQL은 기본 스칼라 유형 세트와 함께 제공됩니다.23)
대부분의 GraphQL 서비스 구현에는 사용자 지정 스칼라 유형을 지정하는 방법도 있습니다. 예를 들어, Date 유형을 정의할 수 있습니다.29)
scalar Date
그런 다음 해당 유형을 직렬화, 역직렬화 및 검증하는 방법을 정의하는 것은 구현에 달려 있습니다. 예를 들어 Date 유형이 항상 정수 타임스탬프로 직렬화되도록 지정할 수 있으며 클라이언트는 모든 날짜 필드에 대해 해당 형식을 예상해야 합니다.30)
Enumeration Types
Enums 이라고도 하는 열거형 유형은 특정 허용 값 집합으로 제한되는 특수한 종류의 스칼라입니다. 이를 통해 다음을 수행할 수 있습니다.31)
GraphQL 스키마 언어에서 열거형 정의는 다음과 같습니다.34)
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
이것은 스키마에서 Episode 유형을 사용할 때마다 정확히 NEWHOPE, EMPIRE 또는 JEDI 중 하나일 것으로 예상한다는 것을 의미합니다.35)
다양한 언어로 된 GraphQL 서비스 구현에는 열거형을 처리하는 고유한 언어별 방법이 있습니다. 열거형을 일급 시민으로 지원하는 언어에서 구현은 이를 활용할 수 있습니다. 열거형을 지원하지 않는 JavaScript와 같은 언어에서 이러한 값은 내부적으로 정수 집합에 매핑될 수 있습니다. 그러나 이러한 세부 사항은 열거형 값의 문자열 이름 측면에서 완전히 작동할 수 있는 클라이언트로 누출되지 않습니다.36)
Lists and Non-Null
개체 유형, 스칼라 및 열거형은 GraphQL에서 정의할 수 있는 유일한 유형의 유형입니다. 그러나 스키마의 다른 부분이나 쿼리 변수 선언에서 형식을 사용 하는 경우 해당 값의 유효성 검사에 영향을 주는 추가 형식 수정자를 적용할 수 있습니다. 예를 살펴보겠습니다.37)
type Character {
name: String!
appearsIn: [Episode]!
}
여기서는 String유형을 사용하고 유형 이름 뒤에 느낌표 !를 추가하여 Non-Null로 표시합니다. 이것은 우리 서버가 항상 이 필드에 대해 null이 아닌 값을 반환할 것으로 예상하고 실제로 GraphQL 실행 오류를 트리거하는 null 값을 얻게 되면 클라이언트에게 문제가 있음을 알릴 것을 기대한다는 것을 의미합니다.38)
Null이 아닌 유형 수정자는 필드에 대한 인수를 정의할 때도 사용할 수 있습니다. 그러면 GraphQL 문자열이든 변수든 상관없이 해당 인수로 null 값이 전달되면 GraphQL 서버가 유효성 검사 오류를 반환합니다.39)
query DroidById($id: ID!) {
droid(id: $id) {
name
}
}
VARIABLES
{
"id": null
}
{
"errors": [
{
"message": "Variable \"$id\" of non-null type \"ID!\" must not be null.",
"locations": [
{
"line": 1,
"column": 17
}
]
}
]
}
목록은 비슷한 방식으로 작동합니다. 유형 수정자를 사용하여 유형을 목록으로 표시할 수 있습니다. 이는 이 필드가 해당 유형의 배열을 반환함을 나타냅니다. 스키마 언어에서 이는 유형을 대괄호 [ 및 ]로 묶어 표시합니다. 유효성 검사 단계에서 해당 값에 대한 배열을 예상하는 인수에 대해 동일하게 작동합니다.40)
Non-Null 및 List 수정자를 결합할 수 있습니다. 예를 들어 Null이 아닌 문자열 목록이 있을 수 있습니다.41)
myField: [String!]
즉, 목록 자체는 null일 수 있지만 null 멤버는 포함할 수 없습니다. 예를 들어 JSON에서:42)
myField: null // valid myField: [] // valid myField: ['a', 'b'] // valid myField: ['a', null, 'b'] // error
이제 null이 아닌 문자열 목록을 정의했다고 가정해 보겠습니다.43)
myField: [String]!
이는 목록 자체가 null일 수 없지만 null 값을 포함할 수 있음을 의미합니다.44)
myField: null // error myField: [] // valid myField: ['a', 'b'] // valid myField: ['a', null, 'b'] // valid
필요에 따라 Non-Null 및 List 수정자를 임의로 중첩할 수 있습니다.45)
Interfaces
많은 유형 시스템과 마찬가지로 GraphQL은 인터페이스를 지원합니다. 인터페이스는 유형이 인터페이스를 구현하기 위해 포함해야 하는 특정 필드 세트를 포함하는 추상 유형입니다.46)
예를 들어, Star Wars 3부작의 모든 캐릭터를 나타내는 Character 인터페이스가 있을 수 있습니다.47)
interface Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
즉, Character를 구현하는 모든 유형에서는 인수 및 반환 유형이 정확한 필드가 있어야 합니다.48)
예를 들어 다음은 Character를 구현할 수 있는 몇 가지 유형입니다.49)
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
}
이 두 유형 모두 Character 인터페이스의 모든 필드를 가지고 있지만 특정 유형의 캐릭터와 관련된 추가 필드, totalCredits, starships 및 primaryFunction도 가져오는 것을 볼 수 있습니다.50)
인터페이스는 개체 또는 개체 집합을 반환하려는 경우에 유용하지만 여러 유형이 있을 수 있습니다.51)
예를 들어 다음 쿼리는 오류를 생성합니다.52)
query HeroForEpisode($ep: Episode!) {
hero(episode: $ep) {
name
primaryFunction
}
}
VARIABLES
{
"ep": "JEDI"
}
{
"errors": [
{
"message": "Cannot query field \"primaryFunction\" on type \"Character\". Did you mean to use an inline fragment on \"Droid\"?",
"locations": [
{
"line": 4,
"column": 5
}
]
}
]
}
Hero 필드는 Character 유형을 반환합니다. 즉, 에피소드 인수에 따라 Human 또는 Droid가 될 수 있습니다. 위 쿼리에서 PrimaryFunction을 포함하지 않는 Character 인터페이스에 있는 필드만 요청할 수 있습니다.53)
특정 객체 유형에 대한 필드를 요청하려면 인라인 조각을 사용해야 합니다.54)
query HeroForEpisode($ep: Episode!) {
hero(episode: $ep) {
name
... on Droid {
primaryFunction
}
}
}
VARIABLES
{
"ep": "JEDI"
}
{
"data": {
"hero": {
"name": "R2-D2",
"primaryFunction": "Astromech"
}
}
}
Union Types
Union 유형은 인터페이스와 매우 유사하지만 유형 간에 공통 필드를 지정하지 못합니다.56)
union SearchResult = Human | Droid | Starship
스키마에서 SearchResult 유형을 반환할 때마다 Human, Droid 또는 Starship을 얻을 수 있습니다. 공용체 유형의 구성원은 구체적인 객체 유형이어야 합니다. 인터페이스 또는 다른 공용체에서 공용체 유형을 만들 수 없습니다.57)
이 경우 SearchResult 공용체 유형을 반환하는 필드를 쿼리하는 경우 인라인 프래그먼트를 사용해야 모든 필드를 쿼리할 수 있습니다.58)
{
search(text: "an") {
__typename
... on Human {
name
height
}
... on Droid {
name
primaryFunction
}
... on Starship {
name
length
}
}
}
{
"data": {
"search": [
{
"__typename": "Human",
"name": "Han Solo",
"height": 1.8
},
{
"__typename": "Human",
"name": "Leia Organa",
"height": 1.5
},
{
"__typename": "Starship",
"name": "TIE Advanced x1",
"length": 9.2
}
]
}
}
__typename 필드는 클라이언트에서 서로 다른 데이터 유형을 구별할 수 있는 문자열로 확인됩니다.59)
또한 이 경우 Human과 Droid는 공통 인터페이스(Character)를 공유하므로 여러 유형에 걸쳐 동일한 필드를 반복할 필요 없이 공통 필드를 한 곳에서 쿼리할 수 있습니다.60)
{
search(text: "an") {
__typename
... on Character {
name
}
... on Human {
height
}
... on Droid {
primaryFunction
}
... on Starship {
name
length
}
}
}
이름은 여전히 Starship에 지정되어 있습니다. 그렇지 않으면 Starship이 캐릭터가 아닌 경우 결과에 표시되지 않기 때문입니다!61)
Input Types
지금까지는 열거형이나 문자열과 같은 스칼라 값을 필드에 인수로 전달하는 것에 대해서만 이야기했습니다. 그러나 복잡한 객체를 쉽게 전달할 수도 있습니다. 이것은 생성할 전체 객체를 전달하려는 mutations의 경우에 특히 유용합니다. GraphQL 스키마 언어에서 입력 유형은 일반 객체 유형과 완전히 동일하지만 유형 대신 input 키워드를 사용합니다.62)
input ReviewInput {
stars: Int!
commentary: String
}
mutation에서 입력 객체 유형을 사용하는 방법은 다음과 같습니다.63)
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!"
}
}
}
입력 개체 유형의 필드는 자체적으로 입력 개체 유형을 참조할 수 있지만 스키마에서 입력 및 출력 유형을 혼합할 수는 없습니다. 또한 입력 개체 유형은 해당 필드에 인수를 가질 수 없습니다.64)
Continue Reading
관련 문서
__typename field resolves to a String which lets you differentiate different data types from each other on the client.