rzaripov.kz

GraphQL и PHP: простой клиент для запросов к API

GraphQL позволяет клиенту получать только те поля объекта, которые действительно нужны, вместо загрузки полного ответа REST API. Запросы передаются в виде текста, а сервер возвращает JSON со структурой data и, при необходимости, разделом errors. Такой формат хорошо подходит для мобильных и настольных приложений с изменяемыми экранами.

PHP-клиент можно собрать без специализированной библиотеки: расширение cURL отправляет запрос, а json_encode и json_decode преобразуют данные. Минимальная реализация должна учитывать сетевые сбои, код ответа HTTP, корректность JSON и ошибки уровня GraphQL, которые нередко возвращаются вместе с успешным статусом 200.

Для backend-части приложений Android, iOS, Windows, macOS и Linux, которые разрабатывает Равиль Зарипов, PHP может выступать единой точкой обмена с внешними сервисами. Пример ниже показывает, как выделить сетевой вызов в отдельную функцию и отдельно обработать результат запроса.

Подготовка PHP-окружения

Для запуска потребуются PHP 8.1 или новее, расширения curl и json, а также доступный GraphQL-эндпоинт. Проверить установленные расширения можно через php -m, а наличие cURL — вызовом curl_version(). Composer для этого варианта не нужен, хотя он пригодится при подключении Guzzle или Laravel.

Адрес API и секреты следует хранить в переменных окружения или файле конфигурации, недоступном из публичной директории. Это особенно важно для сервисных токенов: значение, записанное непосредственно в PHP-файл, может случайно попасть в репозиторий или журнал сборки.

Перед началом работы нужно изучить схему GraphQL и проверить операцию в GraphiQL либо через аналогичный интерфейс. Имена запросов, полей и аргументов должны соответствовать серверной схеме. Продакшен-сервер обычно не требует интроспекции для каждого вызова, поэтому документация и разрешённые операции помогают избежать лишних запросов к API.

Формат запроса и переменные

Операция GraphQL описывает структуру получаемых данных. В простейшем случае запрос содержит тип операции query, имя операции, переменные и набор запрошенных полей:

query ProductById($id: ID!) {
  product(id: $id) {
    id
    name
    price
    currency
  }
}

Значения пользовательских данных лучше передавать через variables, а не вставлять в строку запроса. Сервер подставляет переменные по типу ID!, String или Int, после чего применяет собственные правила валидации. Такой подход снижает риск ошибок при экранировании и позволяет повторно использовать одну операцию с разными аргументами.

В PHP текст запроса удобно хранить в переменной, а входные значения — в отдельном массиве:

$query = <<<'GRAPHQL'
query ProductById($id: ID!) {
  product(id: $id) {
    id
    name
    price
    currency
  }
}
GRAPHQL;

$variables = ['id' => '42'];

Для изменяющих данных используется операция mutation, а для получения событий в реальном времени обычно требуется WebSocket-подключение. Простой HTTP-клиент подходит для запросов и мутаций, но не заменяет полноценный транспорт для подписок.

Минимальный клиент на cURL

Функция ниже принимает адрес API, текст запроса, переменные и дополнительные заголовки. Она отправляет JSON методом POST, ограничивает время ожидания и разделяет сетевую ошибку, неуспешный HTTP-ответ и некорректный JSON.

function graphqlRequest(
    string $endpoint,
    string $query,
    array $variables = [],
    array $headers = []
): array {
    $payload = json_encode(
        ['query' => $query, 'variables' => $variables],
        JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    $requestHeaders = array_merge(
        ['Content-Type: application/json', 'Accept: application/json'],
        $headers
    );

    $curl = curl_init($endpoint);

    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => $requestHeaders,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
    ]);

    $body = curl_exec($curl);

    if ($body === false) {
        $message = curl_error($curl);
        throw new RuntimeException("Ошибка соединения с GraphQL API: {$message}");
    }

    $status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);

    if ($status < 200 || $status >= 300) {
        throw new RuntimeException("Сервер GraphQL API вернул HTTP {$status}");
    }

    $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

    if (!is_array($result)) {
        throw new RuntimeException('Ответ GraphQL API не является JSON-объектом');
    }

    return $result;
}

После подготовки функции вызов выглядит достаточно коротко:

$endpoint = (string) getenv('GRAPHQL_ENDPOINT');

$result = graphqlRequest(
    $endpoint,
    $query,
    ['id' => '42']
);

$product = $result['data']['product'] ?? null;

Перед вызовом нужно убедиться, что переменная GRAPHQL_ENDPOINT не пустая. В рабочем приложении адрес API, таймауты и параметры повторных попыток обычно выносят в отдельный конфигурационный класс.

Разбор ответа и ошибок

GraphQL может вернуть раздел errors даже при HTTP-статусе 200. Это означает, что проверка только кода ответа cURL недостаточна: транспорт успешно доставил запрос, но сервер не смог выполнить операцию целиком или выполнил её частично.

Ошибки удобно преобразовать в исключение или в типизированный результат приложения:

if (!empty($result['errors'])) {
    $messages = [];

    foreach ($result['errors'] as $error) {
        $messages[] = $error['message'] ?? 'Неизвестная ошибка GraphQL';
    }

    throw new RuntimeException(implode('; ', $messages));
}

$product = $result['data']['product'] ?? null;

Сетевой сбой, код 401, превышение таймаута и ошибка резолвера требуют разных реакций. Первые случаи иногда допускают повторный запрос, ошибку авторизации обычно решают обновлением токена, а не повторяют тот же вызов без изменений. Автоматические попытки безопаснее применять к идемпотентным запросам.

Пользователю интерфейса лучше показывать короткое понятное сообщение, а полный ответ API сохранять в серверном журнале. Там можно зафиксировать код ошибки, идентификатор запроса и контекст операции, не записывая секреты и персональные данные.

Авторизация и защищённые заголовки

Если API требует токен, его передают в заголовке Authorization в формате Bearer. Значение следует получать из защищённого хранилища и добавлять только к обращению на нужный хост:

$token = getenv('GRAPHQL_TOKEN');

$headers = $token !== false
    ? ["Authorization: Bearer {$token}"]
    : [];

$result = graphqlRequest($endpoint, $query, $variables, $headers);

Секретный токен не должен попадать в клиентское мобильное приложение, браузерный JavaScript или общедоступный репозиторий. Если GraphQL обслуживает мобильных пользователей, PHP-сервер обычно получает их учётные данные, выполняет обмен токенами и обращается к защищённому API от своего имени.

Следует также использовать HTTPS, проверять домен сертификата и контролировать время ожидания. Значения заголовков должны формироваться из доверенных источников: нельзя передавать пользовательский ввод как часть имени или значения заголовка без проверки. Для отдельных операций могут понадобиться идентификатор tenant, версия API или трассировочный идентификатор.

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

PHP-функцию можно использовать непосредственно в контроллере, а при росте проекта перенести в клиентский класс или сервис GraphQL. Отдельный слой легче тестировать, централизует авторизацию и позволяет добавить журналирование, повторные попытки или кэширование без изменения бизнес-логики.

Такой шаблон полезен, когда веб-интерфейс должен передать исходник в сервис конвертации PSD-файлов, получить идентификатор задачи и опрашивать внутренний GraphQL-эндпоинт для получения результата. Здесь PHP отвечает за обмен с сервисом, а пользовательский интерфейс получает только необходимые сведения о задаче.

Для больших наборов данных лучше использовать курсорную пагинацию, ограничивать глубину вложенных полей и избегать выполнения множества отдельных запросов внутри цикла. Если ответы редко меняются, краткоживущий кэш снижает нагрузку на API. При разработке клиентские запросы стоит проверять на тестовом сервере с зафиксированной схемой и контролируемыми ответами.

Сравнение способов реализации

Выбор зависит от размера проекта и используемой инфраструктуры. Прямой cURL не требует зависимостей, но добавляет собственную обработку ошибок. Guzzle сокращает сетевой код и предоставляет middleware, а HTTP-клиент Laravel органично сочетается с настройкой окружения, тестами и очередями.

Подход Сильные стороны Ограничения Подходящий сценарий
Прямой cURL Нет внешних зависимостей, полный контроль запроса Нужно самостоятельно реализовать обработку ошибок и повторные попытки Небольшие скрипты и независимые PHP-сервисы
Guzzle Удобные middleware, тестовые адаптеры, поддержка PSR-7 Требуется Composer и дополнительная зависимость Проект со стандартизированной HTTP-инфраструктурой
HTTP-клиент Laravel Интеграция с конфигурацией, авторизацией, тестами и очередями Привязка к фреймворку и его жизненному циклу Приложения, в которых уже используется Laravel

Для компактного самостоятельного клиента cURL остаётся наиболее предсказуемым решением, а при наличии Composer, Guzzle или Laravel разумно использовать уже настроенные сетевые инструменты проекта.