1. Что такое GraphQL

GraphQL — это язык запросов для API и среда выполнения этих запросов. Разработан в Facebook в 2012 году, открыт в 2015-м. Сегодня его используют GitHub, Twitter, Shopify, Airbnb и тысячи других компаний.

REST vs GraphQL: главное отличие

Представь: тебе нужно показать карточку пользователя — имя, аватар и его последние 3 поста.

С REST придётся делать так:

GET /users/123          # получаем пользователя
GET /users/123/posts    # получаем все посты (их может быть 500!)

Проблемы:

• Overfetching — /users/123 возвращает 30 полей, нужно только 2
• Underfetching — нужно 2 запроса вместо одного
• Версионирование — /api/v1/, /api/v2/ — боль при изменениях

С GraphQL — один запрос:

query {
  user(id: "123") {
    name
    avatar
    posts(limit: 3) {
      title
      createdAt
    }
  }
}

Получаешь ровно то, что запросил:

{
  "data": {
    "user": {
      "name": "Алексей",
      "avatar": "https://cdn.example.com/avatar.jpg",
      "posts": [
        { "title": "Мой первый пост", "createdAt": "2026-01-01" },
        { "title": "GraphQL — огонь!", "createdAt": "2026-01-15" },
        { "title": "TypeScript tips", "createdAt": "2026-02-01" }
      ]
    }
  }
}

Три операции GraphQL

Операция	REST-аналог	Назначение
query	GET	Получение данных
mutation	POST/PUT/DELETE	Изменение данных
subscription	WebSocket	Real-time обновления

Как работает GraphQL

Клиент → HTTP POST → GraphQL сервер → Resolvers → БД/API
                           ↓
                      Схема (Schema)
                   (типы + валидация)

1. Клиент отправляет запрос на единственный endpoint (/graphql)
2. Сервер валидирует запрос против схемы
3. Resolver — функция, которая знает, как получить данные для каждого поля
4. Ответ — только запрошенные данные в формате JSON

Ключевые преимущества

1. Один endpoint

REST:    /users, /posts, /comments, /likes, /notifications...
GraphQL: /graphql  ← всё здесь

2. Строгая типизация из коробки

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  posts: [Post!]!
}

Схема — это контракт между клиентом и сервером. Клиент всегда знает, какие поля доступны и какого типа.

3. Интроспекция

GraphQL умеет сам себя документировать:

query {
  __schema {
    types {
      name
      fields {
        name
        type {
          name
        }
      }
    }
  }
}

GraphiQL и Apollo Studio используют это для автодополнения и документации.

4. Нет версионирования API

В REST при изменении API нужна новая версия. В GraphQL просто добавляешь новые поля — старые клиенты продолжают работать, новые используют новые поля.

type User {
  id: ID!
  name: String!
  email: String!
  # Новые поля не ломают старых клиентов:
  phoneNumber: String
  twoFactorEnabled: Boolean
}

Когда использовать GraphQL

✅ Хорошо подходит:

• Сложные данные с множеством связей
• Несколько клиентов (web, mobile, desktop) с разными нуждами
• Быстро меняющийся продукт
• Публичный API для разработчиков

❌ Может быть лишним:

• Простые CRUD операции
• Файловые операции (загрузка файлов — через REST лучше)
• Маленький проект без сложных связей

Практика

1. Зайди на https://studio.apollographql.com/sandbox — бесплатная GraphQL площадка
2. Попробуй публичный GraphQL API: https://countries.trevorblades.com/graphql
3. Запроси список стран:

query {
  countries {
    name
    code
    capital
    currency
  }
}

Итого

• GraphQL — язык запросов и спецификация для API
• Решает overfetching и underfetching из REST
• Один endpoint /graphql вместо множества routes
• Строгая типизация — схема как контракт
• Три операции: query, mutation, subscription

Следующий урок → Установка Apollo Server и Client →