Проектування 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-пагінації
| Критерій | Курсорна пагінація | Offset-пагінація |
|---|---|---|
| Продуктивність на великих вибірках | O(log n) | O(n) |
| Консистентність при вставках | Стабільна | Дублі/пропуски |
| Реалізація | Трохи складніше | Простіше |
| Підтримка Relay | Так | Ні |
Паттерн 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 кроки
- Картографія полів. Зберіть усі використовувані клієнтом поля через інструменти типу
graphql-inspector. Відсійте невикористовувані. - Профілювання продуктивності. Виміряйте TTFB кожного запиту за допомогою Apollo Studio або Sentry. Виявіть N+1-запити.
- Оптимізація. Впровадьте DataLoader для критичних полів, додайте кешування через
@cacheControl. Скоротіть кількість join'ів.
Приклад структури папок для доменів
schema/ base.graphql products.graphql orders.graphql users.graphql scalars.graphql directives.graphql Розділення схеми за доменами
Для великих проєктів схему розбивають на файли за доменами, як показано вище. Це спрощує підтримку та рев'ю. На практиці такий підхід зменшує конфлікти при злитті гілок на 70%.
Що входить у проєктування схеми під ключ
| Етап | Результат |
|---|---|
| Аналіз UI та бізнес-логіки | Список необхідних типів і операцій |
| Проєктування схеми | Файли .graphql, документація полів |
| Рев'ю з командою фронтенду | Узгоджений контракт |
| Інтеграція з DataLoader | Оптимізація N+1 запитів |
| Розгортання та моніторинг | Налаштування rate limiting, кешування |
Також входить навчання команди роботі зі схемою та підтримка протягом місяця після запуску. Отримайте консультацію — обговоримо ваш проєкт.
Строки
Проєктування схеми для додатку середнього масштабу (5–10 сутностей): 3–5 днів. З рев'ю, документацією та узгодженням: 1 тиждень. Зв'яжіться з нами, щоб обговорити ваш проєкт — оцінимо обсяг та запропонуємо оптимальне рішення. Замовте проєктування схеми під ключ і позбудьтеся проблем з N+1 та неузгодженими інтерфейсами. Наша команда має понад 5 років досвіду та успішно реалізувала понад 100 проєктів у різних доменах.
GraphQL — це не просто технологія, а дисципліна проєктування контракту. Ми гарантуємо, що результат відповідатиме специфікації та очікуванням вашої команди.