{"canonical_url":"https://engineer.company/uk/glossary/graphql/","content_markdown":"# GraphQL\n\n## Що це таке\n\nGraphQL — це мова запитів для API разом із середовищем виконання, яке обробляє\nці запити на сервері. Клієнт надсилає документ, що називає саме ті поля, які\nйому потрібні, і сервер відповідає даними такої самої форми. Специфікація описує\nйого як мову й рушій виконання для клієнт-серверних програм. У ній зазначено, що\nGraphQL створено 2012 року, що роботу над ним як над відкритим стандартом почали\n2015 року і що з 2019 року він є одним із результатів роботи GraphQL\nSpecification Project при Joint Development Foundation. Найновіше видання вийшло\nу вересні 2025 року.\n\nУсе починається зі схеми, яку публікує сервіс: набору типів, кожен з іменованими\nполями, а кожне поле має власний тип. Вбудовані скалярні типи — `Int`, `Float`,\n`String`, `Boolean` і `ID`, а сервіс може додати власні скаляри, наприклад для\nUUID. Будь-який тип допускає null, якщо його не позначено `!`, тож `String!`\nніколи не буде null, а списки записують у квадратних дужках: `[LineItem!]!` — це\nсписок, який завжди присутній і ніколи не містить null. Запити можна надсилати й\nдо самої схеми. Через поля інтроспекції `__schema` і `__type` клієнт може\nспитати сервіс, що той пропонує, і саме на цьому побудовано інструменти\nрозробника та клієнтські бібліотеки.\n\nОперації бувають трьох видів. Операція `query` — це, словами специфікації, «a\nread-only fetch», тобто вибірка лише для читання; `mutation` — це запис, за яким\nіде вибірка; а `subscription` — це довготривалий запит, що доставляє дані у\nвідповідь на послідовність подій у часі. На сервері за кожним полем стоїть\nфункція, яку зазвичай називають резолвером, і вона обчислює значення поля.\nСервіс спершу перевіряє операцію на відповідність схемі й лише потім викликає\nрезолвери для полів, які операція вибрала. Поля верхнього рівня в `mutation`\nвиконуються одне за одним, а не паралельно, тож два записи в одному запиті не\nможуть наввипередки змінювати ті самі дані.\n\nСпецифікація не приписує ні транспорту, ні формату серіалізації. Найпоширеніший\nвибір — HTTP, і тоді GraphQL API доступний за однією URL-адресою, зазвичай із\nзакінченням `/graphql`, і відповідає в JSON, найпоширенішому форматі. Клієнт\nнадсилає POST, у JSON-тілі якого є текст `query` і за потреби `variables`.\nСервер може також приймати GET для операцій `query`, але `mutation` завжди\nнадсилають через POST. У відповіді результат лежить у `data`, а все, що пішло не\nтак, — в `errors`. Настанови GraphQL Foundation щодо всього цього спираються на\nспецифікацію GraphQL-over-HTTP, яка досі є чернеткою.\n\n## Чому це важливо\n\nУ більшості HTTP API сервер вирішує, що повертає кожна кінцева точка. Екран,\nякому потрібні статус замовлення та ім'я покупця, або отримує все замовлення й\nусі дані покупця, тобто більше, ніж просив, або мусить надіслати по запиту на\nкожен ресурс і сам зшити відповіді. Специфікація називає ці дві проблеми\nover-fetching і under-fetching. GraphQL робить навпаки: клієнт запитує на рівні\nокремих полів і отримує саме ці поля, не більше й не менше. Один запит також\nможе йти за зв'язками, від замовлення до його позицій і далі до покупця, бо\nзапит має ту саму форму, що й дані, які він отримає.\n\nСистема типів окупається двічі. Кожну операцію перевіряють на відповідність\nсхемі ще до запуску будь-якого резолвера, тож поле з помилкою в назві чи\nаргумент неправильного типу відхиляються цілком, ще до виконання будь-чого, а\nінструменти можуть ловити ті самі помилки ще під час написання коду. І оскільки\nклієнт отримує лише вибрані ним поля, нове поле нічого не коштує наявним\nклієнтам. Тому API зручно розвивати без номерів версій: нове поле з'являється\nпоруч зі старим, старе позначають `@deprecated` із поясненням причини, воно\nлишається чинним, щоб наявні клієнти не зламалися, і його прибирають, коли жоден\nклієнт ним більше не користується.\n\nЦіна реальна, і здебільшого вона виникає тому, що доводиться виходити за межі\nмеханізмів самого HTTP. Сутності більше не ідентифікуються через URL, і все йде\nна одну адресу, зазвичай через POST, тоді як кешованими за замовчуванням\nзазвичай вважаються саме запити GET. Кешування, яке REST API отримує від\nпосередників задарма, доводиться відбудовувати навмисно. Код стану вже не\nрозповідає всієї історії, бо відповідь, у якій є і дані, і помилки, на рівні\nHTTP однаково вважається успішною. Тепер клієнт складає запити, яких сервер\nніколи не бачив, тож один-єдиний запит може вимагати дуже багато роботи, і\nзахищати від цього сервер — завдання сервісу, а не те, що GraphQL робить за\nнього. Резолвери на рівні полів легко писати, але, написані наївно, вони стають\nнадто балакучими з базою даних, що стоїть за ними.\n\n## Як це виглядає на практиці\n\nНевелика частина схеми для замовлень, кожне з позиціями й покупцем:\n\n```graphql\ntype Query {\n  order(id: ID!): Order\n}\n\ntype Order {\n  id: ID!\n  status: String!\n  items: [LineItem!]!\n  customer: Customer\n}\n\ntype LineItem {\n  name: String!\n  quantity: Int!\n}\n\ntype Customer {\n  name: String!\n}\n```\n\nЕкран, що показує статус, позиції та ім'я покупця, надсилає цю операцію на\n`/graphql` у тілі POST зі змінними `{\"id\": \"7421\"}`:\n\n```graphql\nquery OrderSummary($id: ID!) {\n  order(id: $id) {\n    status\n    items {\n      name\n      quantity\n    }\n    customer {\n      name\n    }\n  }\n}\n```\n\nПрипустімо, що замовлення та його позиції отримано, але сервіс за `customer` не\nпрацює. Відповідь однаково містить усе, що вдалося отримати. Поле, яке не\nвдалося обчислити, повертається як null, а запис в `errors` повідомляє, що пішло\nне так, де в документі це сталося (рядок 8, стовпець 5 — це `customer`) і якого\nшляху у відповіді це стосується:\n\n```json\n{\n  \"data\": {\n    \"order\": {\n      \"status\": \"open\",\n      \"items\": [{ \"name\": \"notebook\", \"quantity\": 2 }],\n      \"customer\": null\n    }\n  },\n  \"errors\": [\n    {\n      \"message\": \"Customer service unavailable\",\n      \"locations\": [{ \"line\": 8, \"column\": 5 }],\n      \"path\": [\"order\", \"customer\"]\n    }\n  ]\n}\n```\n\nОскільки `customer` оголошено таким, що допускає null, шкода зупиняється на\nцьому полі. Якби воно було `Customer!`, помилка поширилася б на батьківське\nполе, і все замовлення повернулося б як null. А оскільки `data` не null, сервер\nвідповідає кодом стану 2xx, хоча помилка є: в HTTP немає коду стану для\nчасткового успіху. Клієнт, який дивиться лише на код стану, сприйме цю відповідь\nяк повну.\n\nПротилежний підхід, коли форму кожної відповіді визначає сервер, реалізував один\nпроєкт із портфоліо цього сайту:\n[наскрізний JSON від Postgres до API](/uk/portfolio/designed-a-json-passthrough-from-postgres-to-api/).\nТам функції PostgreSQL збирають усю відповідь у JSON, а обробник на Go пересилає\nїї без змін, тож коли змінюється те, що повертає функція, змінюється й те, що\nотримує клієнт, і нікому не треба правити жодного рядка коду обробників.\nФронтенд там залежить безпосередньо від форми, яку йому дає база даних. У\nGraphQL поля називає клієнт, і сервер мусить бути готовим видати будь-яку їхню\nкомбінацію, яку дозволяє схема.\n\n## Де виникають проблеми\n\n**Одне поле — тисяча звернень до бази даних.** Резолвери — це маленькі функції,\nпо одній на поле, і наївний сервіс викликає їх по одному об'єкту за раз. Список\nзамовлень із покупцем кожного замовлення тоді коштує одного звернення до бази\nданих для списку й ще одного для кожного замовлення в ньому. Настанови GraphQL\nFoundation називають це проблемою N+1 і вказують на пакетування (batching):\nзавантаження, запитані в межах короткого проміжку часу, збирають разом і\nнадсилають до бази даних одним запитом за допомогою інструмента на кшталт\nDataLoader від Facebook.\n\n**Один запит вимагає всього.** Оскільки операцію пише клієнт, один документ може\nвкладати друзів друзів на багато рівнів углиб, повторити дороге поле під сотнею\nпсевдонімів (aliases) або запакувати багато операцій в один запит. Кожен такий\nдокумент — валідний GraphQL, і кожен може надовго зайняти сервер. Захищатися має\nсервіс: розбивайте поля-списки на сторінки, відхиляйте операції, що перевищують\nмаксимальну глибину чи ширину, ще до початку виконання, обмежуйте кількість\nпсевдонімів і операцій в одному запиті, а для тоншого контролю призначайте полям\nвагу й відхиляйте будь-яку операцію, чия оцінена вартість перевищує бюджет. Цей\nприйом відомий як аналіз складності запитів (query complexity analysis), і сама\nспецифікація не дає для нього жодних правил. API, що обслуговує лише власних\nклієнтів, може піти далі з довіреними документами (trusted documents): тоді\nвиконуватися можуть лише операції, збережені заздалегідь і знайдені за хешем.\n\n**200 OK приховує збій.** Відповідь із помилками однаково може мати код 2xx, як\nу прикладі вище. Зі старішим медіатипом `application/json` настанови йдуть далі:\n2xx рекомендовано навіть тоді, коли валідний запит не вдається виконати, а деякі\nзастарілі сервери повертають 2xx і для помилок валідації. Клієнт і моніторинг\nнавколо нього мусять читати `errors`, а не лише код стану. Новіший медіатип\n`application/graphql-response+json` повертає коду стану сенс, бо валідний запит,\nякий не вдалося виконати, тоді отримує 4xx або 5xx, і клієнтам варто просити\nсаме його в заголовку `Accept`.\n\n**Кешування перестає працювати.** Кожна операція — це POST на ту саму\nURL-адресу, тож кеші між клієнтом і сервером, зокрема CDN, бачать одну адресу й\nметод, який вони за замовчуванням не кешують. Допомагає надсилати операції\n`query` через GET, але довгий документ може перевищити довжину URL, яку\nприймають браузери та CDN. Збережені запити (persisted queries) розв'язують\nобидві проблеми: клієнт надсилає хеш, а сервер знаходить за ним повний документ,\nперш ніж валідувати й виконати його. Скрізь, де відповіді кешуються через HTTP,\nчутливі відповіді треба кешувати приватно або не кешувати взагалі.\n\n**Поле зникає.** Клієнти обирають поля по одному, тож якщо поле прибрати чи\nперейменувати, ламається кожен клієнт, який досі його вибирає, і ламається не\nм'яко: операція, що згадує невідоме поле, цілком не проходить валідацію й не дає\nжодних даних. Специфікація лишає застарілі поля чинними саме для того, щоб не\nламати наявних клієнтів. Спершу додайте заміну, позначте старе поле\n`@deprecated` із причиною, що вказує на нове, і прибирайте старе поле лише тоді,\nколи його вже ніщо не вибирає.\n\n## Що почитати далі\n\n- [GraphQL Specification Versions](https://spec.graphql.org/) — усі видання\n  специфікації, від липня 2015 року до видання вересня 2025 року, плюс робоча\n  чернетка: мова, система типів, валідація, виконання й помилки.\n- [Serving over HTTP](https://graphql.org/learn/serving-over-http/) — одна\n  кінцева точка, POST і GET, два медіатипи відповідей і правила кодів стану для\n  кожного з них.\n- [Performance](https://graphql.org/learn/performance/) — GET для операцій\n  `query`, persisted queries, проблема N+1 і пакетування.\n- [Security](https://graphql.org/learn/security/) — trusted documents, обмеження\n  глибини, ширини й кількості операцій у запиті, query complexity analysis, а\n  також інтроспекція й деталі помилок у продакшені.\n\n\u003chttps://engineer.company/uk/glossary/graphql/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"Як GraphQL дає клієнтові обрати поля, які він отримає, чого коштує одна кінцева точка в кешуванні й кодах стану і п'ять способів, як усе ламається.","formats":{"gemtext":"https://engineer.company/uk/glossary/graphql/index.gmi","gopher":"https://engineer.company/uk/glossary/graphql/gophermap","html":"https://engineer.company/uk/glossary/graphql/","json":"https://engineer.company/uk/glossary/graphql/index.json","markdown":"https://engineer.company/uk/glossary/graphql/index.md","pdf":"https://engineer.company/uk/glossary/graphql/index.pdf"},"kind":"page","language":"uk","title":"Що таке GraphQL?","url":"https://engineer.company/uk/glossary/graphql/","version":1}