> For the complete documentation index, see [llms.txt](https://kaze.gitbook.io/qa-theory/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kaze.gitbook.io/qa-theory/web/chto-takoe-graphql.md).

# Что такое GraphQL?

**GraphQL** — это язык запросов к API и среда их выполнения, разработанный Facebook как альтернатива REST.

***

#### Особенности GraphQL

1. **Клиент сам выбирает данные**
   * В одном запросе можно указать, какие именно поля нужны.
   * Сервер вернёт только эти данные.
2. **Один эндпоинт**
   * В отличие от REST, где много URL (например, `/users`, `/users/1/orders`), в GraphQL всё идёт через один endpoint (обычно `/graphql`).
3. **Строгая типизация**
   * Данные описаны в виде схемы (Schema), где указаны типы объектов, их поля и доступные операции.
4. **Поддержка трёх типов операций**
   * **Query** — чтение данных (аналог GET).
   * **Mutation** — изменение данных (аналог POST/PUT/DELETE).
   * **Subscription** — подписка на обновления (реальное время, аналог WebSocket).

***

#### Преимущества

* Клиент получает ровно то, что нужно (нет «overfetching» и «underfetching»).
* Один запрос может объединять данные из разных источников.
* Поддержка работы в реальном времени через подписки.

***

#### Недостатки

* Сложнее в настройке, чем REST.
* Повышенная нагрузка на сервер (сложные запросы).
* Нужен контроль глубины запросов (иначе можно «уронить» сервер рекурсией).

***

#### Для QA важно

* Проверять корректность схемы (SDL).
* Тестировать разные типы операций: Query, Mutation, Subscription.
* Проверять обработку ошибок при запросе несуществующих полей.
* Тестировать перформанс при сложных вложенных запросах.

***

Пример запроса и ответа в **GraphQL**:

#### Запрос (Query)

Клиент хочет получить только имя и email пользователя с id = 1:

```graphql
query {
  user(id: 1) {
    name
    email
  }
}
```

***

#### Ответ сервера

Сервер вернёт **только те поля**, что были запрошены:

```json
{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}
```

***

#### Пример мутации (Mutation)

Добавим нового пользователя:

```graphql
mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
    email
  }
}
```

***

#### Ответ сервера

```json
{
  "data": {
    "createUser": {
      "id": "2",
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}
```

***

Таким образом, клиент управляет тем, **какие именно данные получить или изменить**, а сервер возвращает ровно этот набор.

#### Пример **Subscription** в GraphQL

**Задача:** клиент хочет получать в реальном времени новые сообщения в чате.

***

#### Запрос подписки (Subscription)

```graphql
subscription {
  newMessage {
    id
    text
    author {
      name
    }
  }
}
```

***

#### Как это работает

1. Клиент открывает подписку через WebSocket.
2. Каждый раз, когда на сервере появляется новое сообщение, сервер **сам отправляет** данные подписчикам.

***

#### Пример ответа сервера при новом сообщении

```json
{
  "data": {
    "newMessage": {
      "id": "101",
      "text": "Привет!",
      "author": {
        "name": "Alice"
      }
    }
  }
}
```

***

Таким образом, **Query и Mutation** работают как обычные запросы (клиент → сервер), а **Subscription** — это канал от сервера к клиенту для событий в реальном времени.