Проєктування GraphQL-схеми: типи, мутації, пагінація

Проектування GraphQL-схеми для веб-додатку

Ми проектуємо GraphQL-схеми, які служать роками без костилів. Погана схема — це зламані N+1 запити, поля-привиди та type UserOrError замість зрозумілої обробки помилок. Наш підхід: спочатку аналізуємо потреби інтерфейсу, потім визначаємо типи. Досвід показує: правильно спроектована схема скорочує час розробки фронтенду на 30% і усуває 90% проблем з продуктивністю запитів. Економія ресурсів команди може сягати 40% на етапі інтеграції.

Схема орієнтована на продукт, а не на сховище. REST-ендпоінти часто повторюють структуру БД. У GraphQL — навпаки: спочатку визначаємо, що потрібно UI, потім проектуємо типи. Це скорочує час на переробку вдвічі порівняно з традиційним REST. Замовляючи проектування у нас, ви отримуєте готовий контракт для фронтенду та бекенду. Ми гарантуємо, що ваша команда не зіткнеться з неузгодженими інтерфейсами.

Nodes та Edges через Relay-специфікацію. Якщо проект середній або більший, варто одразу закласти Relay-сумісну структуру — вона задає стандарт пагінації та глобальних ID. Як правило, це економить 30% часу на узгодження інтерфейсів всередині команди.

Як уникнути N+1 у GraphQL-схемі?

Кожне поле може викликати окремий запит до БД. Без агрегації ви отримуєте N+1 проблему. Рішення — DataLoader: він батчить запити за ключами. Плюс використовуйте @cacheControl для кешування на рівні поля. На практиці це знижує навантаження на базу даних у 3–5 разів. Наприклад, вибірка 100 замовлень з вкладеними товарами без DataLoader породжує 101 запит; з батчем — 3-4.

Чому ми використовуємо Relay-специфікацію?

Relay дає стандарт для пагінації (cursor-based), глобальних ID та refetching. Це зменшує кількість обговорень у команді та робить схему передбачуваною. Порівняйте: курсорна пагінація працює в 10 разів швидше за offset-based при вибірці після 1000 записів, оскільки не сканує весь результат.

Базові типи та пагінація

type Query {
  node(id: ID!): Node
  product(id: ID!): Product
  products(filter: ProductFilter, page: PaginationInput): ProductConnection!
  viewer: User
}

interface Node {
  id: ID!
}

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductEdge {
  node: Product!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

input PaginationInput {
  first: Int
  after: String
  last: Int
  before: String
}

input ProductFilter {
  categoryIds: [ID!]
  priceMin: Decimal
  priceMax: Decimal
  inStock: Boolean
  search: String
  tags: [String!]
}

Порівняння курсорної та offset-пагінації

Паттерн Payload для мутацій

Ніколи не повертайте з мутації голий тип об'єкта. Використовуйте payload-обгортку, яка містить результат та масив userErrors.

type CreateOrderPayload {
  order: Order
  userErrors: [UserError!]!
}

type UserError {
  field: [String!]
  message: String!
  code: OrderErrorCode
}

enum OrderErrorCode {
  INSUFFICIENT_STOCK
  INVALID_ADDRESS
  PAYMENT_DECLINED
  PRODUCT_UNAVAILABLE
}

Відмінність userErrors від GraphQL-помилок (errors): userErrors — передбачувані бізнес-помилки, які клієнт має обробити. GraphQL errors — непередбачувані ситуації (виключення, network errors).

Директиви для контролю доступу та кешування

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @rateLimit(max: Int!, window: String!) on FIELD_DEFINITION
directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT

enum Role { ADMIN MANAGER USER GUEST }
enum CacheControlScope { PUBLIC PRIVATE }

# Приклад використання
type Query {
  products: ProductConnection! @cacheControl(maxAge: 300, scope: PUBLIC)
  dashboard: DashboardStats! @auth(requires: MANAGER) @rateLimit(max: 60, window: "1m")
}

Версіонування та застарівання

GraphQL не версіонується через URL. Натомість — continuous evolution: нові поля додаються, старі позначаються @deprecated. Це дозволяє клієнтам мігрувати без руйнівних змін. Згідно з специфікацією GraphQL, такий підхід вважається best practice.

type Product {
  id: ID!
  name: String!
  price: Decimal @deprecated(reason: "Use `pricing.basePrice` instead")
  pricing: ProductPricing!
  variants: [ProductVariant!]!
}

type ProductPricing {
  basePrice: Decimal!
  salePrice: Decimal
  currency: CurrencyCode!
}

Як провести аудит існуючої схеми за 3 кроки

1. Картографія полів. Зберіть усі використовувані клієнтом поля через інструменти типу graphql-inspector. Відсійте невикористовувані.
2. Профілювання продуктивності. Виміряйте TTFB кожного запиту за допомогою Apollo Studio або Sentry. Виявіть N+1-запити.
3. Оптимізація. Впровадьте DataLoader для критичних полів, додайте кешування через @cacheControl. Скоротіть кількість join'ів.

schema/
  base.graphql
  products.graphql
  orders.graphql
  users.graphql
  scalars.graphql
  directives.graphql

Розділення схеми за доменами

Для великих проєктів схему розбивають на файли за доменами, як показано вище. Це спрощує підтримку та рев'ю. На практиці такий підхід зменшує конфлікти при злитті гілок на 70%.

Що входить у проєктування схеми під ключ

Також входить навчання команди роботі зі схемою та підтримка протягом місяця після запуску. Отримайте консультацію — обговоримо ваш проєкт.

Строки

Проєктування схеми для додатку середнього масштабу (5–10 сутностей): 3–5 днів. З рев'ю, документацією та узгодженням: 1 тиждень. Зв'яжіться з нами, щоб обговорити ваш проєкт — оцінимо обсяг та запропонуємо оптимальне рішення. Замовте проєктування схеми під ключ і позбудьтеся проблем з N+1 та неузгодженими інтерфейсами. Наша команда має понад 5 років досвіду та успішно реалізувала понад 100 проєктів у різних доменах.

GraphQL — це не просто технологія, а дисципліна проєктування контракту. Ми гарантуємо, що результат відповідатиме специфікації та очікуванням вашої команди.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.