GraphQL 포매터

GraphQL을 정렬하는 이유

GraphQL 쿼리는 코드 안에서 조립되거나, 로그에 한 줄로 찍히거나, 브라우저의 네트워크 기록에서 복사되는 경우가 많습니다. 몇 단계만 중첩되어도 이런 형태의 쿼리는 읽기가 거의 불가능합니다. 어떤 필드가 어느 객체에 속하는지, 프래그먼트가 어디서 끝나는지 알 수 없습니다. GraphQL 포매터가 필요한 이유입니다.

GraphQL 포매터는 필드를 한 줄에 하나씩 놓고, 모든 선택 세트(selection set)를 부모보다 한 단계 더 들여씁니다. 그러면 쿼리의 구조가 돌아오는 응답의 구조와 똑같아져서 확인하기 쉬워집니다.

이 도구는 Prettier 3와 GraphQL 플러그인을 브라우저에서 실행합니다.

사용 방법

1. 왼쪽 상자에 쿼리, 뮤테이션 또는 스키마를 붙여넣습니다. 붙여넣자마자 정렬됩니다.
2. 또는 파일 열기를 눌러 .graphql 파일을 불러오거나, 예시를 눌러 예제를 봅니다.
3. 들여쓰기를 고릅니다. 공백 2칸, 공백 4칸, 탭 중에서 선택합니다.
4. 줄 너비를 고릅니다. 이 너비에 들어가지 않는 인자와 변수 목록은 여러 줄로 나뉩니다.
5. 포맷을 누르거나 Ctrl+Enter를 누릅니다.
6. 복사를 누르거나, 다운로드를 눌러 .graphql 파일로 저장합니다.

한 번 포맷한 뒤에는 입력에 맞춰 결과가 따라 바뀝니다. 문법 오류가 있으면 메시지가 줄과 열을 알려 주고, 입력에서 보기를 누르면 그 위치로 이동합니다.

정렬 전과 후

한 줄짜리 쿼리입니다.

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

공백 2칸으로 포맷한 결과입니다.

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

변수의 콜론 뒤에 공백이 들어가고, 기본값 5의 = 양쪽에 공백이 생기며, 중첩된 선택 세트가 모두 들여쓰기됩니다. 이제 title이 posts 안의 edges 안에 있는 node의 필드라는 것이 한눈에 보입니다.

뮤테이션과 입력 객체

줄 너비 안에 들어가는 입력 객체는 한 줄로 유지됩니다.

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

들어가지 않으면 인자가 나뉩니다. 다음은 같은 뮤테이션을 줄 너비 40으로 정렬한 결과입니다.

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

여러 줄로 펼쳐진 객체에서는 입력 필드 사이의 쉼표가 빠진다는 점에 주의하세요. GraphQL에서 쉼표는 선택 사항이며 공백으로 취급됩니다.

프래그먼트

프래그먼트와 스프레드는 작성한 순서 그대로 유지됩니다.

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

스키마 파일

스키마 정의 언어(SDL)도 같은 규칙으로 정렬됩니다. 필드는 한 줄에 하나씩, enum 값도 각각 한 줄씩 놓입니다.

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

들여쓰기를 공백 4칸으로 설정하면 query{viewer{login}}은 다음과 같이 바뀝니다.

query {
    viewer {
        login
    }
}

문법 오류

GraphQL 파서는 엄격하고 메시지는 짧습니다. 위치는 한국어로, 오류 내용은 파서가 내는 영어 그대로 표시됩니다. 자주 보는 두 가지는 다음과 같습니다.

• 마지막에 닫는 중괄호가 빠지면 4행 1열: Syntax Error: Expected Name, found <EOF>.가 나옵니다. 파서가 선택 세트 안에 있는 상태로 입력의 끝(EOF)에 도달했다는 뜻입니다.
• user(id: )처럼 값이 없는 인자는 2행 12열: Syntax Error: Unexpected ")".를 냅니다.

표시된 위치부터 중괄호 개수를 세어 보세요. 긴 쿼리에서 빠진 중괄호를 찾을 때도 포매터가 빠릅니다. 붙여넣었을 때 오류가 입력의 끝을 가리킨다면 닫히지 않은 선택 세트가 있는 것입니다.

한계

• 문법만 확인합니다. 필드 이름, 인자 타입, 필수 변수는 어떤 스키마와도 대조하지 않습니다.
• 필드 순서를 바꾸거나, 타입을 정렬하거나, 쓰지 않는 프래그먼트를 지우지 않습니다.
• JavaScript나 TypeScript의 gql 템플릿 문자열 안에 있는 쿼리는 쿼리 텍스트만 여기에 붙여넣어 정렬한 뒤 결과를 다시 넣으세요. 자바스크립트 포매터와 타입스크립트 포매터는 주변 코드는 정렬하지만 템플릿 문자열은 그대로 둡니다.
• 변수는 GraphQL이 아니라 JSON으로 전송됩니다. 변수 객체는 JSON 포매터에서 정렬하세요.

GraphQL을 정렬하는 다른 방법

• VS Code: Prettier 확장을 설치하면 Format Document(문서 서식) 명령이 .graphql과 .gql 파일을 이 페이지와 같은 규칙으로 정렬합니다. 단축키는 Windows에서 Shift+Alt+F, macOS에서 Shift+Option+F입니다.
• 명령줄: npx prettier --write schema.graphql
• GraphQL IDE: GraphiQL 같은 IDE에는 에디터 안의 쿼리를 정렬하는 Prettify 버튼이 있습니다. 테스트하는 동안에는 이쪽이 편하고, IDE 없이 텍스트만 가지고 있을 때는 이 페이지가 유용합니다.