Документация / 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 могут быть причины отступить от них, но делайте это осознанно и записывайте причину.
| Элемент | Соглашение | Пример |
|---|---|---|
| Поля | camelCase | firstName, createdAt |
| Аргументы | camelCase | userId, includeArchived |
| Типы | PascalCase | User, ProductConnection |
| Перечисления | PascalCase | OrderStatus, Currency |
| Значения перечислений | SCREAMING_SNAKE_CASE | IN_PROGRESS, COMPLETED |
| Интерфейсы | PascalCase | Node, Timestamped |
| Объединения | PascalCase | SearchResult, 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 с множеством бизнес-операций |
| Сущность первой | Группирует по сущностям, легко искать | Неуклюж для операций вне CRUD | API в основном из 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!
}
Свои скаляры
Свои скаляры добавляют проверку и смысл сверх встроенных типов. Используйте их для значений определённого формата или с ограничениями:
| Скаляр | Вместо | Назначение |
|---|---|---|
DateTime | String | Метка времени ISO 8601 с часовым поясом |
Date | String | Календарная дата без времени |
Email | String | Проверенный адрес электронной почты |
URL | String | Корректный URL |
UUID | ID или String | Стандартный уникальный идентификатор |
JSON | String | Произвольный 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 г.
