Лекція 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 — це спосіб отримати певні дані з сервера. Суть у тому, що клієнт сам вибирає, що йому потрібно. Це як замовити бургер у ресторані — ти можеш вибрати, чи хочеш лише котлету або повний набір з різними toppings.

Приклад запиту:

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: схеми, запити, мутації та підписки. Гарна новина: ми не просто теоретизували — на наступних лекціях усе це буде реалізовано на практиці. Готуйтесь до кодування!