Документация / GraphQL

Рекомендации по проектированию

Спецификация GraphQL намеренно умалчивает о ряде важных для API вопросов: работа с сетью, авторизация, пагинация. Это не значит, что в GraphQL для них нет решений, — просто они лежат за пределами описания того, что такое GraphQL, и относятся к общей практике.

Рекомендации ниже — не догма: в некоторых случаях их вполне можно проигнорировать в пользу другого подхода. Страница собрана из разделов «Best Practices» руководства graphql.org: «Мышление графами», «Проектирование схемы» и «Соглашения об именовании».

Мышление графами

С GraphQL предметная область моделируется как граф

Графы — мощный инструмент моделирования многих явлений реального мира: они похожи на наши естественные мысленные модели и словесные описания процессов. В GraphQL предметная область описывается графом через схему: в схеме определяются виды узлов и то, как они связаны друг с другом. На клиенте получается шаблон, похожий на объектно-ориентированное программирование: типы ссылаются на другие типы. На сервере GraphQL задаёт только интерфейс, поэтому его можно использовать с любым backend — новым или унаследованным.

Общий язык

Давать имена трудно, но важно для понятного API

Считайте схему GraphQL выразительным общим языком команды и пользователей. Чтобы построить хорошую схему, присмотритесь к повседневному языку, которым вы описываете свой бизнес. Например, опишем почтовое приложение простыми словами:

  • у пользователя может быть несколько почтовых ящиков;
  • у каждого ящика есть адрес, входящие, черновики, удалённые и отправленные;
  • у каждого письма есть отправитель, дата получения, тема и текст;
  • письмо нельзя отправить без адреса получателя.

Давать имена трудно, но это важная часть понятного API, поэтому не спешите и подумайте, что разумно для вашей предметной области и пользователей. Команда должна прийти к общему пониманию и согласию насчёт правил предметной области: вам предстоит выбрать понятные и долговечные имена узлов и связей схемы GraphQL. Представьте запросы, которые захотите выполнять.

Количество непрочитанных писем во входящих всех моих ящиков:

{
  accounts {
    inbox {
      unreadEmailCount
    }
  }
}

«Краткие сведения» о первых 20 черновиках основного ящика:

{
  mainAccount {
    drafts(first: 20) {
      ...previewInfo
    }
  }
}

fragment previewInfo on Email {
  subject
  bodyPreviewSentence
}

Слой бизнес-логики

Слой бизнес-логики должен быть единственным источником истины для правил предметной области

Где определять собственно бизнес-логику? Где выполнять проверки и авторизацию? Ответ — в отдельном слое бизнес-логики. Он должен быть единственным источником истины для правил предметной области: все точки входа в систему (REST, GraphQL, RPC) обрабатываются по одним правилам проверки, авторизации и обработки ошибок.

Работа с унаследованными данными

Стройте схему GraphQL по тому, как клиенты используют данные, а не по схеме унаследованной базы данных

Иногда приходится работать с унаследованными источниками данных, которые плохо отражают то, как клиенты используют данные. Тогда стройте схему GraphQL по тому, как клиенты используют данные, а не повторяйте схему старой базы.

Выражайте в схеме GraphQL «как», а не «что». Тогда реализацию можно улучшать, не ломая интерфейс для старых клиентов.

Шаг за шагом

Получайте подтверждения и обратную связь чаще

Не пытайтесь смоделировать всю предметную область за один раз. Стройте только ту часть схемы, которая нужна для одного сценария. Постепенно расширяя схему, вы будете чаще получать подтверждения и обратную связь и придёте к правильному решению.

Проектирование схемы

Версионирование

Ничто не мешает версионировать сервис GraphQL, как любой другой API, но GraphQL твёрдо стоит за отказ от версий и даёт инструменты для непрерывного развития схемы.

Почему большинство API версионируют? Когда возвращаемые данные плохо контролируются, любое изменение может оказаться ломающим, а ломающие изменения требуют новой версии. Если для новых возможностей нужна новая версия, приходится выбирать между частыми выпусками со множеством версий и понятностью и сопровождаемостью API.

GraphQL же возвращает только явно запрошенные данные, поэтому новые возможности добавляются новыми типами или новыми полями существующих типов — без ломающих изменений. Отсюда распространённая практика: всегда избегать ломающих изменений и предоставлять API без версий.

На практике это значит:

  • новые поля и типы добавляйте свободно;
  • старое поле помечайте @deprecated(reason: …) с указанием замены и удаляйте после перехода клиентов;
  • не меняйте тип и обязательность существующих полей и аргументов — это ломает клиентов.

Обязательность

В большинстве систем типов, знающих о null, есть обычный тип и его вариант, допускающий null: по умолчанию типы null не включают, пока это не объявлено явно. В системе типов GraphQL наоборот — каждое поле по умолчанию допускает null. В сетевом сервисе с базами данных и другими сервисами многое может пойти не так: база данных упадёт, асинхронное действие не выполнится, возникнет исключение. Помимо сбоев системы, авторизация бывает детальной, и у отдельных полей запроса — разные правила доступа.

Раз каждое поле по умолчанию допускает null, по любой из этих причин null вернёт только это поле, а не провалится весь запрос. Для гарантий GraphQL предлагает обязательные варианты типов: они обещают клиенту, что запрошенное поле никогда не вернёт null. Если же возникнет ошибка, null получит предыдущее поле-родитель.

Проектируя схему GraphQL, помните обо всём, что может пойти не так, и решайте, подходит ли null для поля, которое не удалось вычислить. Обычно подходит, но иногда нет — тогда используйте обязательные типы.

null всплывает к родителю. Если обязательное поле вернуло null, GraphQL передаёт null ближайшему родителю, который допускает null. Если ниже не удалось вычислить email, null станет весь user:

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

type User {
  id: ID!
  name: String!
  email: String!
}

Списки. Для полей-списков используйте [Item!]! — клиент получит пустой массив, а не null:

type User {
  id: ID!
  posts: [Post!]!
  comments: [Comment!]!
}

Входные значения. У входных типов три варианта: поле не передано, передан явный null, передано значение. Это важно для частичных обновлений, когда клиенту нужно очистить необязательное поле:

input UpdateUserInput {
  id: ID!

  "Значение — обновить, null — очистить, не передано — оставить как есть"
  bio: String

  "Значение — обновить, не передано — оставить как есть (очистить нельзя)"
  name: String
}

Какой бы вариант вы ни выбрали, опишите поведение в описаниях полей.

Соглашения об именовании

Спецификация GraphQL не задаёт соглашений об именовании. Ниже — шаблоны, которые хорошо себя показали в боевых API. Это соглашения, а не жёсткие правила: у вашего API могут быть причины отступить от них, но делайте это осознанно и записывайте причину.

ЭлементСоглашениеПример
ПоляcamelCasefirstName, createdAt
АргументыcamelCaseuserId, includeArchived
ТипыPascalCaseUser, ProductConnection
ПеречисленияPascalCaseOrderStatus, Currency
Значения перечисленийSCREAMING_SNAKE_CASEIN_PROGRESS, COMPLETED
ИнтерфейсыPascalCaseNode, Timestamped
ОбъединенияPascalCaseSearchResult, MediaItem
ДирективыcamelCase@include, @semanticNonNull
  • Логические поля начинайте с is или has: isActive, hasSubscription. Этот шаблон есть и в самой спецификации — isDeprecated в типах интроспекции.
  • Поля-списки называйте существительными во множественном числе: posts, а одиночное значение — featuredPost.
  • Поля запросов называйте по данным, которые они возвращают, без глаголов: user(id:) и posts(first:), а не getUser и fetchPosts. Тип операции уже говорит, что это запрос, а get и fetch расходятся с именами вложенных полей.

Имена изменений

Для имён изменений есть два шаблона, оба хорошо работают в боевых API:

# Глагол первым
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateProduct(input: UpdateProductInput!): UpdateProductPayload!
  deletePost(id: ID!): DeletePostPayload!
  sendPasswordResetEmail(email: String!): SendPasswordResetPayload!
}

# Сущность первой
type Mutation {
  userCreate(input: CreateUserInput!): CreateUserPayload!
  productUpdate(input: UpdateProductInput!): UpdateProductPayload!
  postDelete(id: ID!): DeletePostPayload!
  passwordResetEmailSend(email: String!): SendPasswordResetPayload!
}
ШаблонПлюсыМинусыКогда подходит
Глагол первымЕстественный язык, удобен для операций вне CRUDПо алфавиту изменения разбросаныAPI с множеством бизнес-операций
Сущность первойГруппирует по сущностям, легко искатьНеуклюж для операций вне CRUDAPI в основном из CRUD, большие схемы

Последовательность важнее выбора шаблона.

Входные типы и payload-типы

Все входные типы называйте с суффиксом Input: CreateUserInput, UpdateProductInput, SearchFiltersInput.

Изменения возвращают не сами сущности, а структурированные payload-типы: в них можно добавить ошибки проверки и связанные сущности, не ломая существующих клиентов:

input CreateUserInput {
  email: String!
  name: String!
}

type User {
  id: ID!
  email: String!
  name: String!
}

type UserError {
  "Поле ввода, к которому относится ошибка"
  field: String
  message: String!
}

type CreateUserPayload {
  user: User
  userErrors: [UserError!]!
}

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

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

Свои скаляры

Свои скаляры добавляют проверку и смысл сверх встроенных типов. Используйте их для значений определённого формата или с ограничениями:

СкалярВместоНазначение
DateTimeStringМетка времени ISO 8601 с часовым поясом
DateStringКалендарная дата без времени
EmailStringПроверенный адрес электронной почты
URLStringКорректный URL
UUIDID или StringСтандартный уникальный идентификатор
JSONStringПроизвольный JSON, когда нужна гибкость схемы
# Без своих скаляров — ни проверки, ни понятного формата
type User {
  id: ID!
  email: String!
  createdAt: String!
  avatarUrl: String
}

# Со своими скалярами — схема сама себя документирует и проверяет
type User {
  id: ID!
  email: Email!
  createdAt: DateTime!
  avatarUrl: URL
}

Свои скаляры переносят проверку на уровень GraphQL: некорректные значения отклоняются ещё до резолверов. Спецификации распространённых скаляров собраны на scalars.graphql.org.

Но у своих скаляров есть цена: их нужно реализовать в каждом клиенте и сервере, они снижают переносимость и добавляют сложности. Используйте их, когда:

  • у формата есть чёткие правила проверки (адреса почты, URL, даты);
  • одни и те же ограничения у нескольких полей;
  • генерации кода клиентов полезно различать типы.

Не заводите скаляры для строк, которые на деле просто подчиняются бизнес-правилам, вроде Username или ProductCode, — их лучше проверять в резолверах.

Ошибки

GraphQL поддерживает два взаимодополняющих подхода к ошибкам: массив errors верхнего уровня — для исключительных сбоев инфраструктуры и системы, и ошибки как данные (типизированные поля ошибок прямо в схеме) — для ожидаемых нарушений бизнес-правил («нет на складе», «заказ уже оплачен»). Ошибки предметной области возвращайте данными — в payload-типе (userErrors: [UserError!]!) или объединением результатов: так клиент видит их в схеме.

Анти-паттерны

Идентификаторы вместо объектов. Моделируйте связи рёбрами графа, а не внешними ключами:

# Не так
type Post {
  id: ID!
  title: String!
  authorId: ID!
}

# А так
type Post {
  id: ID!
  title: String!
  author: User!
}

Повторение структуры базы данных. Схема отражает предметную область, а не таблицы:

# Не так
type UserTable {
  user_id: Int!
  first_name: String
  last_name: String
  created_timestamp: String
}

# А так
type User {
  id: ID!
  name: String!
  createdAt: DateTime!
  profile: UserProfile
}

Проверка в редакторе

Редактор GraphQL «Помощника SA» проверяет синтаксис и корректность схемы по мере ввода: неизвестные типы, повторные определения, реализацию интерфейсов, допустимость типов аргументов. Кнопка «ИИ-ревью» проверяет схему по рекомендациям этой страницы — именование, обязательность полей, payload-типы мутаций, пагинация, эволюция через @deprecated — и предлагает исправления.

Обновлено: 17 октября 2026 г.