Лекция 282: Основные концепции GraphQL

Сегодня мы углубимся в ключевые концепции GraphQL. Мы обсудим схемы, запросы, мутации и подписки — четыре кита, на которых держится GraphQL. А ещё мы разберем, как эти концепции помогают разрабатывать более гибкие и удобные API.

Что такое схемы и типы в GraphQL?

Схема (Schema) — это основные правила, которые определяют, как клиент может взаимодействовать с сервером. Она служит для строгой типизации вашего API. Можно сказать, что схема — это договор между сервером и клиентом: "Вот как ты можешь со мной общаться!"

Пример схемы в GraphQL:

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

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

В этом примере:

• У нас есть тип Query, который определяет, какие данные можно запрашивать:
  • Поле hello возвращает строку.
  • Поле user возвращает объект типа User, принимая обязательный параметр id (ID!).

• Определён тип User, который описывает объект пользователя:
  • Поля id, name и email строго типизированы.

Основные типы GraphQL

GraphQL предлагает несколько стандартных типов данных (Scalar Types):

• String — строка.
• Int — целое число.
• Float — число с плавающей точкой.
• Boolean — логическое значение.
• ID — уникальный идентификатор (по сути, строка).

Пример использования этих типов:

type Product {
    id: ID!
    name: String!
    price: Float!
    inStock: Boolean
}

Здесь Product описывает товар:

• Поле price — это число с плавающей точкой (например, 1299.99).
• Поле inStock необязательно (Boolean без !), поэтому оно может быть null.

Расширенные типы

GraphQL также поддерживает:

• Enum (перечисления): фиксированный набор значений.

    enum Role {
  ADMIN
  USER
  GUEST
  }
  

• Input (входные объектные типы): используются для передачи сложных данных.

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

• Union и Interface: для описания гибких иерархий типов данных.

Запросы (Queries): Как просить данные

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

Пример запроса:

query {
    user(id: "123") {
        name
        email
    }
}

Ответ сервера:

{
  "data": {
    "user": {
      "name": "Джон Смит",
      "email": "john@example.com"
    }
  }
}

Ключевая идея: клиент запрашивает только нужные данные (name и email) и ничего лишнего.

Аргументы запросов

Запрос user(id: "123") содержит аргумент id. Аргументы позволяют уточнять, какие именно данные нужны. Например:

query {
    product(id: "456") {
        name
        price
    }
}

Ответ сервера:

{
  "data": {
    "product": {
      "name": "Гитара",
      "price": 1299.99
    }
  }
}

Аргументы могут быть скалярными, массивами или даже объектами.

Мутации (Mutations): Как менять данные

Мутации — это действия, изменяющие данные на сервере. Это аналог методов POST/PUT/PATCH/DELETE в REST. Например, чтобы создать нового пользователя, можно использовать следующую мутацию:

mutation {
    createUser(input: {
        name: "Джейн Доу",
        email: "jane@example.com",
        password: "secret"
    }) {
        id
        name
    }
}

Ответ сервера:

{
  "data": {
    "createUser": {
      "id": "789",
      "name": "Джейн Доу"
    }
  }
}

Здесь:

• Ключ createUser указывает на мутацию, создающую нового пользователя.
• Аргумент input передаёт данные для создания.
• Ответ включает созданные данные: id и name.

Отличия мутаций от запросов

У мутаций всегда есть побочные эффекты (side effects), то есть они изменяют состояние данных. Например, добавляют запись в базу данных или обновляют существующую. Запросы же безопасны и просто возвращают данные.

Подписки (Subscriptions): реальное время

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

subscription {
    newMessage {
        id
        content
        sender {
            name
        }
    }
}

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

Ответ клиента может выглядеть так:

{
  "data": {
    "newMessage": {
      "id": "1001",
      "content": "Привет!",
      "sender": {
        "name": "Иван"
      }
    }
  }
}

Применение в реальных проектах

Подписки идеально подходят для сценариев реального времени:

• Чат-приложения.
• Уведомления о статусах заказов.
• Текущие показатели в мониторинговых системах.

Как всё это работает вместе?

GraphQL позволяет комбинировать запросы, мутации и подписки в одном интерфейсе. Например, вы можете:

1. Запрашивать список пользователей (запросы).
2. Создавать новых пользователей (мутации).
3. Автоматически получать уведомления при добавлении новых пользователей (подписки).

Чем GraphQL выигрывает у REST?

Гибкость

В REST выстроено жёсткое соответствие между URI и ресурсами. Например:

• GET /users/123 — возвращает все данные пользователя.
• Но что делать, если клиент хочет только имя?

GraphQL решает эту проблему, позволяя запросить ровно то, что нужно.

Универсальность

GraphQL объединяет разбросанные REST-эндпоинты в одну точку входа. Вместо вызова трёх различных REST-запросов, чтобы собрать данные о пользователе, заказах и товарах, GraphQL позволяет сделать это в одном запросе.

Пример:

query {
    user(id: "123") {
        name
        orders {
            id
            products {
                name
            }
        }
    }
}

Теперь вы знаете, как работают ключевые концепции GraphQL: схемы, запросы, мутации и подписки. Хорошая новость: мы не просто теоретизировали — на следующих лекциях всё это будет реализовано на практике. Готовьтесь к кодингу!