GraphQL форматирование: синтаксис и инструменты

GraphQL — язык запросов для API, разработанный Facebook в 2015 году и опубликованный как открытый стандарт. В отличие от REST, GraphQL предоставляет единую точку доступа и позволяет клиенту точно указывать, какие данные ему нужны.

Базовый синтаксис GraphQL

Query — запрос данных

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      title
      createdAt
    }
  }
}

Mutation — изменение данных

mutation CreatePost($input: PostInput!) {
  createPost(input: $input) {
    id
    title
    author {
      name
    }
  }
}

Фрагменты — повторно используемые блоки

fragment UserFields on User {
  id
  name
  avatarUrl
}

query {
  me { ...UserFields }
  user(id: "1") { ...UserFields }
}

GraphQL vs REST

Критерий	REST	GraphQL
Конечных точек	Много (/users, /posts, ...)	Одна (/graphql)
Over-fetching	Возможен	Нет — клиент задаёт поля
Under-fetching	Требует N+1 запросов	Один запрос для вложенных данных
Версионирование	/v1, /v2	Схема эволюционирует
Кеширование	HTTP-кеш работает	Требует настройки (Apollo, Relay)
Интроспекция	Нет (или OpenAPI отдельно)	Встроена в спецификацию

Зачем форматировать GraphQL запросы

Читаемость: минифицированный запрос в одну строку сложно отлаживать. Форматирование с отступами показывает вложенность полей.

Минификация: для отправки в production-запросах убирают лишние пробелы и переносы, уменьшая размер тела запроса.

Пример минификации:

# Исходный запрос (65 символов с пробелами)
query { user(id: "1") { name email } }

# Минифицированный (36 символов)
query{user(id:"1"){name email}}

Система типов и схема

GraphQL — строго типизированный язык. Схема определяет структуру данных:

type User {
  id: ID!
  name: String!
  email: String
  age: Int
  posts: [Post!]!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
}

! означает non-nullable поле. [Post!]! — non-nullable список non-nullable элементов.

Для работы с JSON-ответами GraphQL используйте JSON форматтер и JSONPath для извлечения данных.

Инструмент на reChecker

Форматтер GraphQL на reChecker приводит запросы к читаемому виду с правильными отступами или минифицирует для отправки. Подсвечивает синтаксические ошибки до выполнения.

Открыть инструмент на reChecker →