GraphQL: рішення для складних систем даних

Вступ: коли REST перестає справлятись

Є певний момент у житті будь-якого продукту, коли архітектура, що добре працювала на старті, починає тріщати по швах.

Мобільний застосунок робить 12 запитів до API, щоб зібрати дані для одного екрану. Фронтенд-розробники чекають, поки бекенд зробить окремий endpoint під нову фічу. Дашборд адміністратора тягне у відповідь масиви даних, з яких використовує 20%. Версіонування API перетворилось на /v1, /v2, /v3 — і жоден з них не можна прибрати, бо хтось іще залежить.

Це не ознака поганих розробників. Це природний наслідок зростання системи поверх архітектури, що не була розрахована на таку складність.

GraphQL з'явився саме як відповідь на цю проблему. Facebook розробив його всередині компанії у 2012 році, коли зіткнувся рівно з такими ж болями при розробці мобільних клієнтів для власної платформи. У 2015-му він став відкритим стандартом — і поступово перетворився на один із ключових інструментів для побудови складних API.

У цій статті — чесна розмова про GraphQL: що це таке, чим відрізняється від REST, де справді виправданий, де ні, і як виглядає на практиці при розробці під ключ.

Частина 1: Що таке GraphQL і як він влаштований

Мова запитів, а не протокол

Перше, що варто зрозуміти: GraphQL — це не протокол передачі даних і не база даних. Це мова запитів для API і середовище виконання цих запитів на сервері.

Ключова ідея: клієнт описує, які саме дані він хоче отримати — і отримує рівно їх. Не більше, не менше.

У REST-архітектурі клієнт звертається до endpoint'у — наприклад, GET /users/42 — і отримує те, що сервер вирішив повернути. Можливо, це ім'я, email, дата реєстрації, список ролей, аватар, налаштування — все одним об'єктом. Клієнту потрібне тільки ім'я і email — але він все одно тягне весь об'єкт.

У GraphQL клієнт надсилає запит, де явно вказує: потрібен об'єкт user з полями name і email. Сервер повертає рівно цей об'єкт із двома полями — і нічого зайвого. Сервер повертає рівно те, про що попросили.

Три основні операції

GraphQL має три типи операцій:

Query — читання даних. Аналог GET в REST. Клієнт запитує дані без побічних ефектів на сервері.

Mutation — зміна даних. Аналог POST / PUT / DELETE. Клієнт описує, що хоче змінити, і отримує у відповідь оновлений стан.

Subscription — підписка на оновлення в реальному часі через WebSocket. Коли дані змінились на сервері — клієнт отримує оновлення без повторного запиту. Корисно для чатів, нотифікацій, live-дашбордів.

Schema як контракт

Центральний елемент GraphQL-архітектури — це Schema. Вона описує всі типи даних, що доступні через API, і всі операції, що можна виконати.

Schema описує всі типи даних і їх зв'язки. Наприклад: тип User містить поля id, name, email і список пов'язаних orders. Тип Order — поля id, total, status і список items. Кожне поле має чіткий тип і позначку обов'язковості.

Schema — це контракт між сервером і клієнтом. Вона машиночитаема, а значить — може автоматично валідувати запити, генерувати типи для TypeScript, живити документацію і підказки в IDE.

Це одна з ключових практичних переваг GraphQL: замість розрізнених документів у Notion або Confluence — єдина Schema, яка завжди актуальна, бо вона і є код.

Частина 2: GraphQL проти REST — чесне порівняння

Проблеми REST, які GraphQL вирішує

Over-fetching — отримання зайвих даних. REST endpoint повертає фіксовану структуру. Якщо вам потрібне тільки поле name із об'єкта user з 30 полями — ви все одно тягнете всі 30. На мобільних мережах це реальна проблема.

Under-fetching — недостатньо даних в одному запиті. Щоб відрендерити сторінку профілю, клієнту потрібен user + його orders + для кожного order — список items. У REST це N+1 запитів або спеціальний endpoint GET /users/42/profile-with-orders, що розрісся під конкретну потребу клієнта.

Жорсткий зв'язок frontend ↔ backend. У REST кожна нова потреба фронтенду часто вимагає нового або зміненого endpoint'у на бекенді. При активній розробці продукту це постійне джерело затримок і координаційних витрат.

Версіонування. Коли API потрібно змінити без злому існуючих клієнтів — з'являється /v2. Потім /v3. Кожна версія потребує підтримки. GraphQL вирішує це через поступове розширення Schema без видалення полів — застарілі поля позначаються @deprecated, але залишаються доступними.

Де REST все ще кращий вибір

Чесна відповідь: GraphQL не є заміною REST у всіх сценаріях.

Прості CRUD-застосунки. Якщо у вас 5 ресурсів і стандартні операції читання і запису — GraphQL додасть складності без відчутної користі. REST простіший у налаштуванні, підтримці і дебагінгу для таких задач.

Публічні API з широкою аудиторією. Twitter, Stripe, GitHub — публічні REST API, якими користуються тисячі розробників. Передбачуваність і простота REST тут важливіша за гнучкість GraphQL. Хоча GitHub вже пропонує і GraphQL API паралельно.

Файловий upload. GraphQL не має вбудованого рішення для завантаження файлів — це вирішується через multipart-розширення або окремий REST endpoint для файлів поруч із GraphQL API.

Кешування на рівні HTTP. REST GET-запити добре кешуються на рівні браузера, CDN і проксі — просто за URL. GraphQL запити — як правило, POST на один endpoint — потребують окремих стратегій кешування (наприклад, APQ — Automatic Persisted Queries, або клієнтський кеш типу Apollo Client).

Коли GraphQL виправданий однозначно

Чим складніша система і чим різноманітніші клієнти — тим більше GraphQL виграє.

Кілька клієнтів із різними потребами: веб-застосунок, мобільний iOS, мобільний Android, адмін-панель — всі використовують один GraphQL API, але кожен запитує рівно ті дані, що потрібні для його інтерфейсу.

Складний граф даних: сутності пов'язані між собою і часто потрібно "проходити" по зв'язках — user → orders → items → products → categories. GraphQL дозволяє описати цей обхід в одному запиті.

Активна розробка продукту з частими змінами вимог: фронтенд-команда може адаптувати запити під нові потреби без очікування бекенду.

Частина 3: Архітектура GraphQL-сервера

Resolvers: серце системи

Якщо Schema описує "що" доступно — то resolvers описують "як" це отримати.

Resolver — це функція, що відповідає за отримання даних для конкретного поля. Коли клієнт запитує user(id: 42) { name, orders { total } } — GraphQL engine викликає resolver для user, потім resolver для orders на отриманому об'єкті user.

Resolvers можуть отримувати дані звідки завгодно: з реляційної бази даних, з NoSQL, з зовнішнього REST API, з кешу, з мікросервісу. GraphQL не диктує джерело даних — він тільки оркеструє отримання.

Resolver для поля user у Query отримує id як аргумент і повертає відповідний запис із бази. Resolver для поля orders у типі User отримує об'єкт користувача і повертає список його замовлень. Кожен resolver — це звичайна асинхронна функція, що звертається до потрібного джерела даних.

Проблема N+1 і DataLoader

Одна з найпоширеніших пасток при наївній реалізації GraphQL — проблема N+1 запитів.

Уявіть: клієнт запитує список із 20 замовлень, і для кожного — дані покупця. Якщо resolver для user в контексті order просто робить db.users.findById(order.userId) — це 20 окремих запитів до бази даних замість одного з WHERE id IN (...).

Рішення — DataLoader, бібліотека від Facebook, що реалізує батчинг і кешування на рівні запиту. Замість 20 окремих запитів — один батчевий. Це не автоматика GraphQL, але стандартний патерн, що використовується в будь-якій серйозній реалізації.

Авторизація і безпека

GraphQL-API має один endpoint — зазвичай /graphql. Це спрощує маршрутизацію, але потребує уважного підходу до безпеки.

Авторизація на рівні resolvers. Перевірка прав доступу відбувається не на рівні URL (як у REST), а всередині кожного resolver'а. Або через middleware-підхід, що перехоплює виконання resolver'ів і перевіряє права до виклику.

Query complexity і depth limiting. GraphQL дозволяє будувати дуже глибокі запити — наприклад, user { friends { friends { friends { ... } } } }. Без обмежень зловмисник може надіслати запит, що рекурсивно обходить велику частину графу даних. Query complexity аналіз і обмеження глибини вкладеності — обов'язкові в продакшн-реалізації.

Introspection у продакшні. GraphQL за замовчуванням дозволяє клієнтам отримати повну Schema через introspection-запит. Зручно для розробки, небажано у відкритому продакшн-API — розкриває структуру всієї системи. Introspection краще вимкнути або обмежити для анонімних клієнтів.

Persisted Queries. Замість того, щоб дозволяти клієнтам надсилати довільні рядки запитів — зареєструвати допустимі запити заздалегідь (як у prepared statements для SQL). Це одночасно підвищує безпеку і дозволяє кешування.

Частина 4: Клієнтська сторона — Apollo, urql і не тільки

Apollo Client: найпопулярніший вибір

Apollo Client — стандарт де-факто для GraphQL на фронтенді. Надає:

Нормалізований кеш. Отримані дані зберігаються в нормалізованому вигляді — кожен об'єкт за своїм ID. Якщо той самий user присутній у декількох запитах — він зберігається один раз. Оновлення в одному місці автоматично оновлює всі компоненти, що використовують цей об'єкт.

Реактивність. Компоненти React (або Vue, Angular) автоматично перерендерюються при оновленні даних у кеші. Патерн useQuery і useMutation інтегруються природно в сучасні React-застосунки.

Optimistic UI. Мутація ще не завершилась на сервері — а інтерфейс вже показує очікуваний результат. Якщо запит провалився — стан відкочується назад. Це дає відчуття миттєвої реакції навіть при повільній мережі.

urql: легша альтернатива

Apollo Client — потужний, але важкий. Для застосунків, де не потрібна вся складність нормалізованого кешу — urql є більш легкою і простішою в налаштуванні альтернативою.

Хороший вибір для менших проектів або команд, що хочуть уникнути overhead Apollo без жертви основними можливостями.

Server Components і GraphQL

З появою React Server Components змінюється і паттерн використання GraphQL. Замість клієнтських запитів через Apollo — запити можуть виконуватись безпосередньо на сервері у Server Component, без клієнтського JS-bundle.

Це змінює рівняння: частина складності Apollo Client (кешування, реактивність) переноситься на серверний рівень. Архітектура GraphQL-клієнта активно еволюціонує в цьому напрямку.

Частина 5: GraphQL у складних системах — федерація і мікросервіси

Проблема: кілька команд, одна Schema

Великий продукт — кілька команд, кожна відповідає за свою частину системи. Команда Users, команда Orders, команда Catalog. У кожної є свій сервіс і своя база даних.

Як побудувати єдиний GraphQL API для клієнтів, якщо дані розподілені між кількома сервісами?

Наївне рішення — API Gateway, що проксіює запити до потрібних сервісів. Але воно швидко стає вузьким місцем і монолітом, що суперечить ідеї мікросервісів.

Apollo Federation: розподілена Schema

Apollo Federation — стандарт, що дозволяє кожній команді визначати і підтримувати власну частину GraphQL Schema незалежно. Ці частини — subgraphs — автоматично компонуються в єдиний граф через Gateway.

Команда Users визначає тип User у своєму subgraph. Команда Orders визначає тип Order і вказує, що він "розширює" User полем orders. При запиті клієнта Gateway автоматично маршрутизує частини запиту до відповідних сервісів і збирає результат.

Кожна команда може деплоїти свій subgraph незалежно. Gateway оновлює composed schema автоматично. Клієнт бачить єдиний API.

Це не проста архітектура — але для великих команд і справді розподілених систем вона дає рівень автономії і масштабованості, якого важко досягти іншими способами.

Коли федерація надмірна

Важливо не переоцінювати складність. Federation має сенс тоді, коли:

• Є кілька окремих команд із власним циклом деплойменту
• Сервіси дійсно розподілені і незалежні
• Розмір системи виправдовує операційну складність

Для однієї команди і одного монолітного застосунку — Federation є зайвою складністю. Монолітна GraphQL Schema цілком справляється.

Частина 6: Практичний погляд на впровадження

Поступова міграція з REST

Перехід на GraphQL не обов'язково означає переписування всього API з нуля. Один із ефективних підходів — "обгортання" існуючих REST API за GraphQL Schema.

GraphQL Gateway стоїть перед існуючими REST сервісами. Resolvers викликають відповідні REST endpoints. Клієнти поступово переходять на GraphQL. З часом "під капотом" можна замінювати REST endpoints на прямі підключення до баз даних — без змін на клієнтській стороні.

Цей підхід дозволяє виміряти реальну цінність GraphQL для конкретної системи, не роблячи великої ставки відразу.

Інструменти розробника, що рятують час

GraphiQL і Apollo Sandbox — інтерактивні IDE для GraphQL у браузері. Автодоповнення, валідація запитів, документація прямо зі Schema. Для фронтенд-розробника можливість досліджувати і тестувати API без Postman або документації — це реальна економія часу.

GraphQL Code Generator — автоматична генерація TypeScript-типів із Schema. Змінилась Schema на бекенді — запускаємо codegen і отримуємо оновлені типи на фронтенді. Менше ручної роботи, менше розбіжностей між контрактом і реалізацією.

Apollo Studio / Hive — платформи для моніторингу GraphQL API: які поля реально використовуються клієнтами, які запити повільні, де є помилки. Особливо важливо при вирішенні питання "чи можна видалити це поле зі Schema?"

Продуктивність: що реально важливо

GraphQL-запити — це завжди POST на один endpoint. Стандартне HTTP-кешування за URL тут не працює.

Основні стратегії продуктивності:

DataLoader для батчингу і дедуплікації — обов'язковий елемент будь-якої реалізації, що має N+1-проблеми.

Persisted Queries — клієнт надсилає хеш запиту замість повного тексту. Сервер знаходить запит за хешем, виконує і повертає результат. Зменшує розмір запитів і дозволяє кешування на CDN.

Response caching на рівні сервера — для даних, що рідко змінюються. Директива @cacheControl в Apollo Server дозволяє задавати TTL для окремих типів і полів.

Query depth і complexity limiting — не тільки безпека, але й продуктивність. Запит з глибиною 15 рівнів і complexity 1000 не має шансів виконатись за прийнятний час.

Висновок: правильний інструмент для правильної задачі

GraphQL — це не срібна куля і не "REST, але краще". Це інструмент із чіткою областю застосування, де він дійсно виграє.

Якщо у вас простий застосунок із кількома ресурсами і стандартними CRUD-операціями — REST буде простішим, швидшим у налаштуванні і в підтримці. Накладати GraphQL на просту систему — значить додавати складність без пропорційної користі.

Але якщо ваша система зростає, якщо у вас різнорідні клієнти з різними потребами в даних, якщо over-fetching і under-fetching перетворились на реальний біль, якщо бекенд-команда витрачає значну частину часу на підтримку endpoint'ів під потреби фронтенду — GraphQL пропонує системне вирішення, а не черговий патч.

Ключові сигнали, що GraphQL виправданий:

• Кілька клієнтів (web, mobile, admin) із різними потребами в даних
• Складний граф пов'язаних сутностей
• Активна розробка, де вимоги до API змінюються часто
• Команда росте і потрібна чітка Schema як контракт

GraphQL змінює розподіл відповідальності: замість того, щоб бекенд вирішував, які дані потрібні клієнту — клієнт описує свої потреби сам. Це не просто технічне рішення. Це інша модель взаємодії між командами, що при правильному впровадженні помітно підвищує швидкість розробки і знижує координаційні витрати.