GraphQL 포매터

실제 예제

형식화 전

query GetUser($id:ID!,$withPosts:Boolean!){user(id:$id){id name email posts @include(if:$withPosts){...PostSummary}}} fragment PostSummary on Post{id title publishedAt}

형식화 후

query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    id
    name
    email
    posts @include(if: $withPosts) {
      ...PostSummary
    }
  }
}

fragment PostSummary on Post {
  id
  title
  publishedAt
}

SDL 스키마

type Post {
  id: ID!
  title: String!
  publishedAt: DateTime
  author: User!
}

type Query {
  post(id: ID!): Post
  posts(authorId: ID, limit: Int = 20): [Post!]!
}

왜 GraphQL을 형식화해야 하나요?

일관된 GraphQL 형식은 code review, schema diff, .graphql 파일 보관에 직접적인 영향을 줍니다. persisted query를 쓸 수 없는 환경에서는 minify로 전송량을 줄일 수 있습니다. 정리된 쿼리는 PR에서 읽기 쉽고, 쿼리를 단독으로 검증하면 빠진 중괄호나 닫히지 않은 문자열 같은 구문 오류를 요청 전에 찾을 수 있습니다. 존재하지 않는 fragment 이름은 구문 오류가 아니므로 스키마 기반 검증이 필요합니다.

동작 원리

본 도구는 브라우저 안에서 graphql-js(GraphQL Foundation이 관리하는 공식 참조 구현)를 실행합니다. parse()가 텍스트로부터 AST를 만들고 첫 구문 오류를 줄·열로 보고합니다. print()가 AST를 표준 GraphQL로 다시 직렬화하고, stripIgnoredCharacters()가 스펙에서 ignored로 정의된 토큰을 모두 제거해 압축 형태를 만듭니다. 네트워크 왕복 없이 모든 처리가 로컬에서 끝납니다.

압축과 오류 예시

위의 “형식화 전” 쿼리에서 압축을 누르면 다음과 같습니다(graphql-js 16.14의 stripIgnoredCharacters).

query GetUser($id:ID!$withPosts:Boolean!){user(id:$id){id name email posts@include(if:$withPosts){...PostSummary}}}fragment PostSummary on Post{id title publishedAt}

GraphQL에서 쉼표는 무시되는 토큰이라 공백과 함께 삭제됩니다. 닫는 중괄호가 하나 빠진 query { user(id: 1) { id name }은 파싱 오류: Syntax Error: Expected Name, found <EOF>. (줄 1, 열 32)로 표시되며, 파서가 입력 끝에 도달한 위치를 가리킵니다.

별칭, 변수와 주석

이 쿼리는 서로 다른 별칭으로 두 사용자를 요청합니다. 공백 4개를 선택하고 형식화를 누르면 중첩된 선택 항목이 나뉩니다. 출력에는 primary, secondary, 따옴표 안의 ID, 변수 기본값과 @include 지시문이 유지됩니다. 맨 앞 주석은 사라지므로 중요한 설명이 있으면 원본 쿼리를 보관하세요. 압축은 같은 작업과 선택 항목을 유지하면서 주석과 파서가 생략을 허용하는 토큰 사이 공백을 삭제합니다.

입력

# Fetch two labels
query Labels($show: Boolean! = true) { primary: user(id: "a") { name } secondary: user(id: "b") @include(if: $show) { name } }

공백 4개 출력

query Labels($show: Boolean! = true) {
    primary: user(id: "a") {
        name
    }
    secondary: user(id: "b") @include(if: $show) {
        name
    }
}

압축 출력

query Labels($show:Boolean!=true){primary:user(id:"a"){name}secondary:user(id:"b")@include(if:$show){name}}

설명 텍스트의 상대적 들여쓰기 유지

설명 텍스트에도 자체 들여쓰기가 있을 수 있습니다. 이 SDL 예제에서 메모는 앞 문장보다 공백 두 개 더 안쪽에서 시작합니다. 공백 4개로 형식화하면 필드와 설명 구분자는 더 넓은 구조적 들여쓰기로 이동합니다. 메모는 여전히 앞 문장보다 공백 두 개 더 안쪽에 있습니다. 형식화한 결과를 다시 파싱하면 줄바꿈과 메모 앞 공백 두 개를 포함하여 입력과 같은 설명 텍스트가 나옵니다.

입력

type Query {
  """
  Returns a label.
    Keep this note indented.
  """
  label: String
}

공백 4개 출력

type Query {
    """
    Returns a label.
      Keep this note indented.
    """
    label: String
}

제한

• 형식화하면 주석이 사라집니다. graphql-js의 print()는 구문 트리에서 텍스트를 다시 만들며 # 주석은 트리에 들어가지 않습니다. 압축도 주석을 지웁니다. 주석이 필요하면 원본 파일을 보관하세요.
• 검증은 구문만 확인합니다. { user(id: $id) { id } }는 $id가 선언되지 않았어도 통과합니다. 변수와 필드 확인에는 스키마가 필요합니다.
• 첫 번째 구문 오류만 보고합니다.
• 4칸 옵션은 중첩으로 생긴 들여쓰기만 넓힙니다. """ 블록 문자열은 시작 줄이 새 들여쓰기로 옮겨 가고, 안의 글은 그 줄에 대한 상대적인 들여쓰기를 유지합니다. GraphQL 명세는 블록 문자열의 공통 들여쓰기만 지우므로, 안쪽 줄까지 넓히면 설명 문구가 바뀌기 때문입니다. graphql-js는 2칸으로 출력하며 다른 도구도 2칸입니다.
• 입력 상한은 10,485,760자입니다.