Запросы и мутации в GraphQL
GraphQL опирается на две основные операции:
Query — безопасные операции чтения данных.
Mutation — операции изменения состояния (создание, обновление, удаление).
Обе операции используют один и тот же язык запросов, отличаются только семантикой:
Query не влияет на состояние системы, Mutation — влияет.
1. Как выглядит запрос (Query)
GraphQL-запрос — декларативное описание структуры данных, которую клиент хочет получить.
Простой пример:
Здесь:
query — тип операции (можно опустить: GraphQL сам определит, что это запрос).
user(id: 42) — вызов поля корневого типа Query.
{ name, avatar } — конкретные поля, которые клиент хочет получить.
GraphQL не вернёт дополнительные поля и не допустит отсутствующих — запрос полностью определяет форму ответа.
Ответ будет ровно такой:
2. Как работает передача аргументов
Аргументы передаются в круглых скобках и могут быть любого типа, определённого в схеме:
скаляры, enum, input-объекты.
Пример схемы:
Пример запроса:
Ответ будет:
2.1. Переменные запроса (не хардкодим аргументы)
GraphQL поддерживает variables, что особенно важно для фронтенда.
Запрос:
Передаваемые переменные:
Сервер объединяет запрос с переменными и выполняет его.
Преимущества переменных:
запрос можно кэшировать,
тело операции не меняется,
безопаснее, чем вставлять значения в строку.
3. Что делает Mutation
Mutation изменяет данные.
Пример схемы:
Пример запроса:
Mutation возвращает объект результата, содержащий новое состояние или подтверждение.
Ответ:
Важный принцип:
Mutation считается одиночной транзакцией.
Даже если внутри происходит много действий, GraphQL гарантирует их упорядоченное выполнение.
4. Возврат данных в нужной форме
GraphQL всегда возвращает данные:
в структуре, которую запросил клиент
в иерархии, описанной в запросе
строго тех типов, которые указаны в схеме
Пример: вложенная выборка.
Ответ:
#Java #middle #GraphQL #Query #Mutation
GraphQL опирается на две основные операции:
Query — безопасные операции чтения данных.
Mutation — операции изменения состояния (создание, обновление, удаление).
Обе операции используют один и тот же язык запросов, отличаются только семантикой:
Query не влияет на состояние системы, Mutation — влияет.
1. Как выглядит запрос (Query)
GraphQL-запрос — декларативное описание структуры данных, которую клиент хочет получить.
Простой пример:
query {
user(id: 42) {
name
avatar
}
}Здесь:
query — тип операции (можно опустить: GraphQL сам определит, что это запрос).
user(id: 42) — вызов поля корневого типа Query.
{ name, avatar } — конкретные поля, которые клиент хочет получить.
GraphQL не вернёт дополнительные поля и не допустит отсутствующих — запрос полностью определяет форму ответа.
Ответ будет ровно такой:
{
"data": {
"user": {
"name": "Den",
"avatar": "https://example.com/den.png"
}
}
}
Никаких “лишних” полей.2. Как работает передача аргументов
Аргументы передаются в круглых скобках и могут быть любого типа, определённого в схеме:
скаляры, enum, input-объекты.
Пример схемы:
type Query {
posts(limit: Int, authorId: ID): [Post!]!
}Пример запроса:
query {
posts(limit: 5, authorId: 42) {
id
title
}
}Ответ будет:
{
"data": {
"posts": [
{ "id": "101", "title": "GraphQL SDL" },
{ "id": "102", "title": "gRPC vs GraphQL" }
]
}
}2.1. Переменные запроса (не хардкодим аргументы)
GraphQL поддерживает variables, что особенно важно для фронтенда.
Запрос:
query GetUser($id: ID!) {
user(id: $id) {
name
avatar
}
}Передаваемые переменные:
{
"id": 42
}Сервер объединяет запрос с переменными и выполняет его.
Преимущества переменных:
запрос можно кэшировать,
тело операции не меняется,
безопаснее, чем вставлять значения в строку.
3. Что делает Mutation
Mutation изменяет данные.
Пример схемы:
type Mutation {
createPost(input: CreatePostInput!): Post!
}Пример запроса:
mutation {
createPost(input: { title: "GraphQL", content: "SDL explained" }) {
id
title
}
}Mutation возвращает объект результата, содержащий новое состояние или подтверждение.
Ответ:
{
"data": {
"createPost": {
"id": "501",
"title": "GraphQL"
}
}
}Важный принцип:
Mutation считается одиночной транзакцией.
Даже если внутри происходит много действий, GraphQL гарантирует их упорядоченное выполнение.
4. Возврат данных в нужной форме
GraphQL всегда возвращает данные:
в структуре, которую запросил клиент
в иерархии, описанной в запросе
строго тех типов, которые указаны в схеме
Пример: вложенная выборка.
query {
user(id: 1) {
name
posts(limit: 2) {
title
comments {
text
}
}
}
}Ответ:
{
"data": {
"user": {
"name": "Den",
"posts": [
{
"title": "GraphQL Basics",
"comments": [
{ "text": "Отличная статья" }
]
},
{
"title": "SDL Tutorial",
"comments": []
}
]
}
}
}
Сервер не может изменить структуру ответа — она определяется клиентом.#Java #middle #GraphQL #Query #Mutation
👍2
5. Ошибки и partial responses
GraphQL всегда возвращает JSON-объект с двумя ключами:
Что важно:
GraphQL может вернуть часть данных, даже если произошла ошибка.
пример: запрос
допустим, поле posts упало из-за ошибки в БД.
Ответ:
GraphQL:
не останавливает выполнение всего запроса,
возвращает то, что смог,
указывает путь к проблемному полю.
Это концепция partial response, которой нет ни в REST, ни в gRPC.
6. Как Mutation обрабатывает ошибки
Mutation также может вернуть частичный результат, но чаще ошибка означает, что произошло отклонение операции:
GraphQL намеренно не использует коды HTTP-статуса, кроме:
200 — запрос обработан
400 — синтаксическая ошибка запроса
500 — ошибка самого сервера GraphQL (не бизнес-ошибка)
#Java #middle #GraphQL #Query #Mutation
GraphQL всегда возвращает JSON-объект с двумя ключами:
data
errors
Что важно:
GraphQL может вернуть часть данных, даже если произошла ошибка.
пример: запрос
query {
user(id: 1) {
name
posts {
title
likes
}
}
}допустим, поле posts упало из-за ошибки в БД.
Ответ:
{
"data": {
"user": {
"name": "Den",
"posts": null
}
},
"errors": [
{
"message": "Database timeout",
"path": ["user", "posts"]
}
]
}GraphQL:
не останавливает выполнение всего запроса,
возвращает то, что смог,
указывает путь к проблемному полю.
Это концепция partial response, которой нет ни в REST, ни в gRPC.
6. Как Mutation обрабатывает ошибки
Mutation также может вернуть частичный результат, но чаще ошибка означает, что произошло отклонение операции:
{
"data": {
"createPost": null
},
"errors": [
{
"message": "User not authorized",
"path": ["createPost"]
}
]
}GraphQL намеренно не использует коды HTTP-статуса, кроме:
200 — запрос обработан
400 — синтаксическая ошибка запроса
500 — ошибка самого сервера GraphQL (не бизнес-ошибка)
#Java #middle #GraphQL #Query #Mutation
👍1