PHP Academy · Урок

GraphQL и REST

Поймите, когда GraphQL эффективнее REST и почему

«GraphQL и REST» — бесплатный урок PHP Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения PHP Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс PHP Academy содержит 4 уроков всего.

Зачем нужен GraphQL

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

В этом уроке мы честно сравним два подхода: где GraphQL действительно выигрывает, где REST по-прежнему лучше подходит и каковы эксплуатационные затраты GraphQL.

Избыточная и недостаточная загрузка данных

Классические проблемы REST:

Избыточная загрузка данных: GET /users/1 возвращает 40 полей, хотя интерфейсу нужны 3.
Недостаточная загрузка данных: чтобы отобразить публикации пользователя и число комментариев к каждой публикации, нужно вызвать /users/1, затем /users/1/posts, а затем N конечных точек комментариев.

GraphQL объединяет всё это в один декларативный запрос.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

Одна конечная точка, типизированная схема

REST предоставляет множество URL, а GraphQL — одну конечную точку (обычно POST /graphql), работающую на основе строго типизированной схемы. Схема является контрактом и поддерживает интроспекцию, поэтому инструменты — автодополнение, документация и генерация кода — доступны сразу.

Ниже приведена минимальная схема на SDL. Структура каждого возможного ответа известна заранее.

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

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

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

Ответ повторяет структуру запроса

Ключевое свойство: структуру ответа JSON можно предсказать по запросу. Клиентам не приходится угадывать имена полей. Это устраняет целый класс проблем с изменением версий: Вы добавляете поля, не ломая старые клиенты, а помечаете поля как устаревшие с помощью @deprecated вместо создания URL /v2.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

Где GraphQL лучше REST

GraphQL лучше выбирать, когда:

Вы обслуживаете множество разнородных клиентов (веб, iOS, Android) с разными потребностями в данных.
Данные образуют граф с глубокими связями, по которым клиенты перемещаются динамически.
Вам нужно объединить несколько серверных частей за одним типизированным шлюзом.
Важны быстрые итерации клиентской части и необходимо избежать бесконечных изменений конечных точек серверной части.

Где REST по-прежнему выигрывает

Не выбирайте GraphQL автоматически. REST проще и часто лучше, когда:

Вам нужно кэширование HTTP — CDN и пограничные кэши используют URL-адреса и методы; единственный POST /graphql для них непрозрачен.
API ориентирован на ресурсы и стабилен (операции создания, чтения, обновления и удаления над несколькими сущностями).
Вы полагаетесь на загрузку и скачивание файлов или потоковую передачу, где multipart-запросы и диапазоны байтов являются стандартными возможностями REST.
Ваши потребители — сторонние разработчики, ожидающие привычной семантики REST.

Краткое сравнение с PHP

Вот как те же данные собираются с помощью REST в PHP — обратите внимание: клиенту всё равно понадобилось бы несколько запросов или пришлось бы вручную формировать параметр встраивания. GraphQL переносит эту логику выбора на клиент.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

Издержки, которые добавляет GraphQL

GraphQL переносит сложность на сервер. Теперь Вам также нужно самостоятельно решать следующие задачи:

Запросы N+1 — вложенные резолверы выполняют по одному запросу к БД для каждого узла, если не объединять их в пакеты (DataLoader).
Ограничение стоимости и глубины запроса — вредоносный глубоко вложенный запрос может вызвать отказ в обслуживании.
Кэширование становится сложнее; обычно кэшируют на уровне резолвера или данных, а не на уровне HTTP.
Обработка ошибок устроена иначе — ответ 200 OK всё равно может содержать массив errors.

Ошибки: 200 с массивом ошибок

В отличие от кодов состояния REST, GraphQL обычно возвращает HTTP 200 и сообщает о частичных сбоях внутри тела ответа. Поле data может быть заполнено частично, а в errors перечисляются сбои. Ваши клиенты должны проверять оба поля.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Практическое правило выбора

Практическое правило:

Публичные API с активным кэшированием и операциями создания, чтения, обновления и удаления над ресурсами → REST.
Внутренние или продуктовые API, предоставляющие разнообразным функционально насыщенным клиентам связанные данные → GraphQL.
Много серверных систем, которые нужно объединить за единым типизированным контрактом → шлюз GraphQL.

Использовать оба подхода — обычная и полезная практика: REST для вебхуков и загрузки файлов, GraphQL для графа данных, которые приложение читает.

Обслуживание GraphQL через HTTP в PHP

С точки зрения эксплуатации конечная точка GraphQL в PHP — это один маршрут, который читает тело JSON, извлекает query и variables, выполняет их относительно схемы и возвращает { data, errors }. В отличие от многочисленных маршрутов REST, транспорт единообразен — все различия находятся в строке запроса, которую отправляет клиент.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

Быстрая проверка

В каких случаях REST сохраняет явное преимущество перед GraphQL?

Повторение

Вы сравнили GraphQL и REST по существу:

GraphQL устраняет избыточную и недостаточную выборку данных с помощью одной типизированной конечной точки и выбора, управляемого клиентом.
Он особенно эффективен при наличии множества клиентов, данных в форме графа и агрегации на серверной стороне.
REST остаётся сильным решением для кэшируемых публичных API, простых операций над ресурсами, загрузки файлов и обычных потребителей.
GraphQL переносит издержки на сервер: запросы N+1, ограничения стоимости запросов, кэширование и семантику ответа 200 с ошибками.

Далее: практическое создание схемы с помощью webonyx/graphql-php.

Часто задаваемые вопросы

Урок «GraphQL и REST» бесплатный?

Да — полный текст урока «GraphQL и REST» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс PHP Academy, подпишись на CoddyKit PRO. Курс PHP Academy содержит 4 уроков всего.

Чему я научусь в уроке «GraphQL и REST»?

Поймите, когда GraphQL эффективнее REST и почему Ты практикуешь PHP Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать PHP Academy?

Предыдущий опыт не требуется. PHP Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «GraphQL и REST»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке PHP Academy?

Да. Каждый урок PHP Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к PHP Academy