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 разумно использовать уже настроенные сетевые инструменты проекта.