GraphQL - 응답

공식 참조 문서
GraphQL 서버가 요청을 받았을 때 올바른 형식의 응답을 반환해야 합니다.서버의 응답은 작업의 결과나 오류를 설명합니다.

1. Serialization Format 시퀀스 형식

1.1 개요

GraphQL에는 특정 시퀀스 형식이 필요하지 않습니다.그러나 클라이언트는 GraphQL 응답의 주요 원어를 지원하는 서열화 형식을 사용해야 합니다.서열화 형식은 다음 네 가지 유형의 표현을 지원해야 합니다.

Map

List

String

Null

여기서 String은 다음과 같은 유형으로 대체할 수 있습니다.

Boolean

Int

Float

Enum Value

1.2 JSON 서열화

우선 순위 지정 형식

GraphQL에서 JSON을 서열화 형식으로 선택합니다.반환된 JSON 객체는 질의에 정의된 필드와 동일한 순서를 갖습니다.

개념적 매핑 관계

GraphQL 개념과 JSON 개념의 매핑 관계:
GraphQL Value
JSON Value
Map
Object
List
Array
Null
null
String
String
Boolean
true or false
Int
Number
Float
Number
Enum Value
String

객체 속성 정렬

JSON 객체는 키 값 쌍의 무질서한 집합이지만 질서정연하게 표시됩니다.다시 말하면 JSON 문자열{ "name": "Mark", "age": 30 }과 { "age": 30, "name": "Mark" }은 같은 값을 가지지만 정렬은 다르다.
GraphQL이 반환하는 서열화된 JSON 객체는 질의에 정의된 필드와 같은 순서입니다.
예를 들어 쿼리가 {name,age}이면 JSON으로 응답하는 GraphQL 서버는 {"name": "마크", "age": 30}에 응답해야 하며 {"age": 30, "name": "마크"}에 응답해서는 안 됩니다.

2. Response Format 응답 형식

GraphQL 작업에 대한 응답은 맵이어야 합니다.응답은 세 가지 최고급 속성이 있습니다: 데이터,errors,extensions.

2.1 data

응답의 첫 번째 속성은 모든 응답의 데이터를 채우는 데이터입니다.데이터 응답의 데이터는 실행 작업의 결과입니다.조회 작업에 대해 이 출력은 모드의 조회 루트 유형의 대상이다.변경 작업에 대해 이 출력은 이 모드의 변경 루트 유형의 대상이다.

만약 실행하기 전에 문법 오류, 정보 부족 또는 검증 오류로 인해 작업이 실패할 경우 이 항목은 존재할 수 없습니다.

실행 중 유효한 응답을 막는 오류가 발생하면 응답 중의 데이터 항목은null이어야 합니다.

{
  "data": {
    "viewer": {
      "name": null,
      "id": "MDQ6VXNlcjE4NTMyODU5"
    }
  }
}

2.2 errors

오류가 발생하면 응답은 속성 errors를 포함해야 합니다.이 항목의 값은 오류 섹션에 설명되어 있습니다.errors 응답은 비어 있지 않은 오류 목록입니다. 모든 오류는 맵입니다.

작업이 완료되었지만 오류가 없으면 errors가 존재할 수 없습니다.

모든 오류는 속성 메시지를 포함해야 합니다. 메시지는 개발자의 오류를 알리는 설명 정보입니다.

만약 오류가 요청한 GraphQL 문서의 특정 점과 관련이 있다면, 이 오류는locations 속성을 포함해야 합니다.locations 속성은 오류 행렬 위치 정보의 목록입니다. 그 중에서 라인과column으로 오류가 몇 줄의 몇 열에서 발생했는지 표시합니다.

만약에 데이터 응답이 존재하지 않거나 응답의 값이null이라면,errors 응답은 비어 있을 수 없습니다. 최소한 하나의 오류를 포함해야 합니다. 이 오류는 왜 데이터가 되돌아오지 않는지 지적해야 합니다.만약 데이터 응답이null이 아니라면, errors 응답은 실행 기간에 발생하는 모든 오류를 포함할 수 있습니다.

{
  "data": null,
  "errors": [
    {
      "message": "Field 'namea' doesn't exist on type 'User'",
      "locations": [
        {
          "line": 3,
          "column": 5
        }
      ]
    },
    {
      "message": "Field 'ida' doesn't exist on type 'User'",
      "locations": [
        {
          "line": 6,
          "column": 5
        }
      ]
    }
  ]
}

2.3 extensions

응답도 속성 extensions를 포함할 수 있습니다.이 속성의 값은 맵입니다.이 속성은 인터페이스 정의자를 위해 보존된 것으로 프로토콜을 확장할 수 있으며 내용에 제한이 없습니다.