GraphQL — это язык запросов к API, в котором клиент сам описывает, какие именно данные ему нужны, и получает в ответе только их, одним запросом.
Язык придумали в Facebook (сейчас Meta) и открыли в 2015 году. В классическом REST API каждый тип данных живёт по своему адресу: пользователь по одному, его заказы по другому, товары в заказе по третьему. Чтобы собрать экран, приходится делать несколько запросов и получать лишние поля. В GraphQL есть одна точка входа, и запрос описывает нужную структуру.
Ещё одна особенность — строгая типизация. Каждое поле в схеме имеет тип, и сервер отклонит запрос, который не соответствует схеме. Это защищает от ошибок на стыке сайта и сервера и помогает редакторам кода подсказывать названия полей. Для проверки запросов существуют интерактивные песочницы: вы вводите запрос, видите ответ и подсказки по полям. Это снижает порог входа и делает отладку наглядной.
Пример
Нужны имя клиента и названия его трёх последних заказов. Запрос выглядит как описание формы ответа: в фигурных скобках перечислены поля name и orders { title }. Сервер возвращает JSON ровно с этими полями, без адреса, телефона и остального.
Как это устроено
- Схема описывает типы данных и связи между ними.
- Запросы (query) читают данные, мутации (mutation) меняют.
- Ответ приходит в формате JSON.
- Схема сама служит документацией: по ней работают подсказки в инструментах.
Где используют
GraphQL популярен там, где много связанных данных и разные клиенты: сайт, мобильное приложение, админка. Его предлагают многие Headless CMS и платформы электронной коммерции, поэтому с ним часто сталкиваются при сборке сайта на Next.js с внешним хранилищем контента.
Типичные ошибки
- Не ограничивать глубину и сложность запросов: клиент может случайно или намеренно запросить огромный объём данных.
- Переносить в GraphQL простое приложение, где хватило бы REST.
- Забыть про кэширование: один адрес для всех запросов усложняет кэш на уровне CDN.
- Открыть мутации без проверки прав.
Чем отличается от REST
В REST сервер решает, какие данные отдать по каждому адресу. В GraphQL решает клиент. REST проще, лучше кэшируется и понятнее новичкам. GraphQL экономит запросы и трафик при сложных экранах.
Частый вопрос
GraphQL лучше REST? Не всегда. Для небольших сайтов и простых форм REST быстрее в разработке. GraphQL выигрывает, когда данных много, они связаны между собой, а клиентам нужны разные срезы.