Что такое Mutation в GraphQL?

Мутация (Mutation) в GraphQL

Мутация (Mutation) в GraphQL — это операция, предназначенная для модификации данных на сервере: создания, обновления или удаления записей. В отличие от запросов (Queries), которые предназначены только для чтения данных и являются идемпотентными, мутации изменяют состояние системы и могут иметь побочные эффекты. Это ключевое концептуальное различие между двумя типами операций в GraphQL.

Основные характеристики мутаций

• Изменение данных: Главная цель — изменять данные (create, update, delete).
• Структура: В схеме GraphQL мутации объявляются в специальном типе Mutation, который является корневым, аналогично типу Query.
• Синтаксис: В теле запроса мутации начинаются с ключевого слова mutation. Можно выполнять несколько мутаций в одном запросе, но они выполняются последовательно, в порядке указания, а не параллельно, как запросы.
• Возвращаемое значение: Мутации всегда возвращают данные, обычно это измененный объект или связанные с ним данные. Это позволяет клиенту за один запрос и изменить данные, и сразу получить обновленную информацию.

Пример мутации в GraphQL

Рассмотрим на примере создания новой статьи в блоге.

Схема GraphQL (SDL):

type Article {
  id: ID!
  title: String!
  content: String!
  publishedAt: String!
}

type Mutation {
  createArticle(title: String!, content: String!): Article!
  publishArticle(id: ID!): Article!
}

Запрос мутации с клиента:

mutation CreateNewArticle {
  createArticle(title: "GraphQL Мутации", content: "Подробное объяснение...") {
    id
    title
    publishedAt
  }
}

Ответ сервера (JSON):

{
  "data": {
    "createArticle": {
      "id": "123",
      "title": "GraphQL Мутации",
      "publishedAt": "2023-10-05T12:00:00Z"
    }
  }
}

Ключевые аспекты и лучшие практики

1. Именование: Принято называть мутации глаголами или действиями (createArticle, updateUserProfile, deleteComment), в то время как поля запросов часто являются существительными.

2. Входные типы (Input Types): Для сложных аргументов мутаций рекомендуется использовать специальные Input-типы. Это улучшает читаемость схемы.

   input ArticleInput {
     title: String!
     content: String!
     authorId: ID!
   }
   
   type Mutation {
     createArticle(input: ArticleInput!): Article!
   }
   

3. Обработка ошибок: Грамотная обработка ошибок критична. Рекомендуется использовать подход union-типов или кастомных ошибок в ответе, а не полагаться только на HTTP-статусы.

   type Mutation {
     publishArticle(id: ID!): PublishArticleResult!
   }
   
   union PublishArticleResult = Article | ArticleNotFoundError | ForbiddenError
   

4. Идемпотентность: Старайтесь проектировать мутации идемпотентными там, где это возможно. Повторный вызов идемпотентной мутации с теми же аргументами не должен изменять состояние системы сверх первого вызова. Это повышает надежность и упрощает повторные запросы при сбоях сети.

5. Побочные эффекты: Мутации часто влекут за собой побочные эффекты: отправку email, инвалидацию кэша, запуск фоновых задач. Это нормально, но важно документировать такое поведение.

Сравнение с REST API

В REST API для модификации данных используются HTTP-методы POST, PUT, PATCH, DELETE. В GraphQL все операции отправляются через POST-запрос на один эндпоинт, а тип операции (чтение или изменение) определяется структурой тела запроса. Это дает GraphQL-мутациям несколько преимуществ:

• Точность данных: Клиент сам определяет, какие данные вернуть после изменения, исключая лишние запросы.
• Атомарность обновлений: Возможность изменить несколько связанных сущностей за один запрос (например, создать заказ и обновить баланс пользователя).
• Более строгая типизация: Система типов GraphQL обеспечивает валидацию входных данных на уровне схемы.

Заключение

Мутация — это фундаментальная и мощная часть GraphQL, ответственная за все операции записи. Ее правильное проектирование, сфокусированное на смысловых действиях, использовании Input-типов и продуманной структуре ответов, напрямую влияет на понятность, надежность и удобство использования API для клиентских разработчиков. В отличие от простого CRUD, мутации в GraphQL лучше отражают бизнес-домен приложения.