Словник для API GraphQL: схема, розв'язувачі, мутації і підписки

GraphQL має свій власний словник, і він різко відрізняється від REST. Якщо ви описуєте API GraphQL за допомогою слів REST — « endpoints », « routes », « GET і POST » — ви звучатимете не дуже глибоко. У цьому довіднику розглянуто основні терміни, дієслова, які використовуються інженерами, а також відмінності (запит проти мутації, поле проти типу), які важливі у розмові.

---

Ментальний зсув: одна кінцева точка, типізований граф

У REST, ви маєте багато ** кінцевих точок **, одну на ресурс. У GraphQL у вас є ** одна кінцева точка ** і ** типова схема **, яка описує всі можливі елементи. Клієнт ** запитує саме ті поля, які йому потрібні ** — ні більше, ні менше.

“Замість того, щоб вдарити п’ять кінцевих точок REST, клієнт відсилає один запит до кінцевої точки GraphQL і запитує саме ті поля, які йому потрібні в одній поїздці в обидві сторони.”

Дві фрази, які описують переваги GraphQL:

• ** Перевантаження ** — отримання більше даних, ніж вам потрібно (задача REST, яку вирішує GraphQL).
• ** Недостатнє отримання ** — потрібні декілька запитів, щоб отримати все (також вирішено).

---

Схема і система типів

** Схема ** є контрактом — вона визначає кожен тип і операцію.

• Type — форма даних, наприклад User, Post.
• Field — властивість типу, наприклад, user.email.
• Скаляр — примітив: String, Int, Boolean, ID, Float.
• Nullable vs. non-null — String може бути нульовим; String! не може.
• ** Enum ** — фіксоване число дозволених значень.
• Interface / union — способи виразити поліморфні типи.
• Input type — тип, який використовується для аргументів (наприклад, корисна нагрузка мутації).
• ** SDL ** — мова визначення схеми, синтаксис, за допомогою якого ви пишете схему.

Колокацій:

• ви ** визначаєте тип ** / ** додаєте поле ** / ** позначаєте поле як не нульове **
• схема ** виставляє ** запит
• поле ** розв’ язує** значення

“Ми визначаємо тип User з не-нульовим полем id і нульовим полем bio. Схема викликає запит user(id: ID!)

Вимова: schema є /ˈskiːmə/ (SKEE-muh). Не “Шема”. Это провоцирует много разговоров.

---

Три типи операцій

У GraphQL є три типи операцій — знайте, що це за типи:

• ** Запит ** — читання даних. (Як GET.)
• ** Mutatio ** — запис/ зміна даних. (Наприклад, POST/ PUT/ DELETE.)
• ** Підписка ** — отримувати оновлення у реальному часі за допомогою постійного з’ єднання.

«Ми виставляємо posts запит для читання, createPost мутацію для запису, і postAdded підписку, щоб клієнти отримували оновлення в реальному часі»

Часта помилка: виклик запису як « запиту ». У GraphQL, * читання — це запити, запис — це мутації.* Якщо ви скажете « Я напишу запит для оновлення користувача », інженер GraphQL виправить вас на « ** мутація **. »

---

Розв’ язувачі: де дані походять

** розв’ язувач ** — це функція, яка створює значення для поля. Це серце сервера GraphQL.

• розв’ язувач розв’ язує поле
• розв’ язувачів ** запуск ** на поле, згори вниз
• розв’ язувач ** отримує ** дані з бази даних або іншої служби

“Резольвер user збирає користувача з Postgres; резольвер user.posts потім розв’язує повідомлення. Кожне поле має свій розв’язувач»

Порівняльні терміни:

• ** Ланцюг розв’ язувачів ** — розв’ язувачі, що викликають вкладені поля.
• ** Контекст ** — спільні дані (аут, завантажувачі) передаються кожному розв’ язувачу.
• ** Корінь розв’ язувача ** — точка входу (Запит, Мутація, Підписка).

---

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

Найбільш часто обговорювана проблема з швидкодією GraphQL:

• Задача N+1 — отримання списку N елементів, а потім виконання N додаткових запитів для вкладених даних кожного елемента (1 + N запитів).
• ** Пакетне отримання ** — об’ єднання багатьох невеликих завантажень у одне.
• ** DataLoader ** — програма, яка ** пакетує ** і ** кешує ** ці отримання у запиті.

«Завантаження 50 постів викликало 50 окремих пошуків авторів — класична N+1 проблема. Ми додали DataLoader для пакетного їх в один запит. ”

Це питання, яке майже гарантовано буде поставлено під час інтерв’ ю для робіт у GraphQL. Умеет определить его в одном предложении.

---

Запит: поля, аргументи, фрагменти, змінні

На стороні клієнта:

• ** Вибір полів ** — вибір повернутих полів.
• ** Аргумент ** — параметр на полі, наприклад user(id: 5).
• ** Змінна ** — заміна динамічних значень з префіксом $.
• ** Фрагмент ** — набір полів, які можна використовувати повторно.
• ** Псевдонім ** — перейменування поля у відповіді.
• ** Директива ** — модифікатор, наприклад @include або @skip.

«Ми витягаємо спільні поля в фрагмент, передаємо ID як змінну, і використовуємо директиву для умовного включення поля email»

---

Порушення, відмова, еволюція

• ** Часткова відповідь ** — GraphQL може повертати дані * і * помилки разом.
• Errors array — де помилки рівня поля з’ являються поруч з data.
• ** Депресія ** — позначає поле як застаріле за допомогою @deprecated(reason: "...") замість вилучення.
• ** еволюція схеми ** — додавання полів безпечно (додатне); вилучення або перейменування поля є ** порушенням зміни **.

«Замість того, щоб вилучити fullName, ми депретекували його з причини і додали firstName / lastName. Додаткові зміни є зворотньо сумісними; видалення є порушенням»

---

REST → GraphQL обмін словником

REST word	GraphQL word
Endpoint / route	Single endpoint + schema
GET	Query
POST / PUT / DELETE	Mutation
Resource	Type
Response field	Field (you select them)
Polling for updates	Subscription

---

Нерідко виникли проблеми з ненадійними інженерами

1. ** Виклик запису як « запиту ». ** Читання — це запити; запис — це ** мутації **.
2. ** Використовується для позначення « кінцевих точок » (множини). ** GraphQL має * одну * кінцеву точку і схему.
3. *Неправильно произношу “schema”. * Это СКЭ-му.
4. ** Плутанина поля і типу. ** ** Тип ** це форма ( User ); ** поле ** це властивість на ній ( email ).
5. **Скажіть « API повертає забагато ». **Використовуйте over- fetching — точний термін.

---

Ключевые вещи

• GraphQL означає одну кінцеву точку, типовану схему, і клієнтів вибір точно тих полів, які їм потрібні.
• Три операції: query (читання), mutation (запис), subscription (реальний час) — ніколи не викликайте запис запиту.
• ** Розв’ язувачі ** створюють значення полів; відома пастка швидкодії — це ** проблема N+1 **, яку розв’ язують за допомогою пакетного розв’ язання ** DataLoader **.
• Розвивати схеми шляхом відновлення, а не вилучення — додавання безпечні, вилучення є розривом змін.
• Вилучіть слова REST, такі як « endpoints » і « routes »; використовуючи власну лексику GraphQL, ви будете вільно говорити.

Mastering GraphQL Vocabulary — Beyond the Basics (англійською)

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

Одна з найпоширеніших проблем виникає при обговоренні продуктивності, особливо проблема N + 1. Легко просто сказати «Ми маємо проблему N+1». Однак, більш корисний підхід — особливо під час перегляду коду — це сформулювати її так: «Поточний результат реалізації розв’язувача — це шаблон запиту N+1 для отримання пов’язаних даних. Це означає, що для кожного елемента, отриманого спочатку, ми виконуємо * N * додаткових запитів для отримання пов’ язаних елементів, що призводить до значного зниження продуктивності, оскільки набір даних зростає. Ми повинні розглянути альтернативні рішення, такі як використання DataLoader або пакетних запитів, щоб зменшити це.» Зауважте деталі — це не просто про ідентифікацію проблеми, але про її вплив і натяки на потенційне рішення. Аналогічно, під час обговорення проектування схеми, уникайте нечітких тверджень на зразок « Схема погано розроблена ». Замість цього, намагайтеся вказати щось на зразок: « У поточній схемі відсутнє чітке визначення типу « orderItems », що призведе до неоднозначності у запитуванні пов’ язаних даних і, можливо, до збільшення складності під час майбутніх модифікацій ». Сфокусування уваги на * ефекті * вибору проекту, а не просто на його « поганому », призведе до продуктивнішої розмови.

Крім того, при описі розв’язувачів - особливо тих, що мають справу зі складними відносинами - використовуйте точну мову. Сказати, що «результат потребує оптимізації» занадто загально. Замість цього спробуйте: « Складність запиту поточного розв’ язувача перевищує прийнятні межі. Зокрема, вкладені операції JOIN сприяють збільшенню затримки і повинні бути переглянуті з використанням більш ефективного шаблону доступу до даних. “Це демонструє розуміння того, чому необхідна оптимізація - це не просто про те, щоб зробити речі швидшими; це про адресування конкретних вузьких місць.

Нарешті, при перегляді чиєїсь коду, пов’ язаного з підписками або мутаціями, уникайте узагальнень типу «це може викликати проблеми з масштабуванням». Більш конструктивний підхід буде таким: «Ця логіка мутації не включає в себе ніяких механізмів обмеження або обмеження швидкості. Без цих заходів безпеки сервер є уразливим до перевантаження надмірними запитами, що може призвести до погіршення якості обслуговування. ” Знову ж таки, специфічність підвищує обговорення від неясного занепокоєння до реальної зворотної зв’ язку.

# Example of DataLoader usage (Conceptual - not a complete solution)
from dataloader import DataLoader

dataloader = DataLoader(
    # Configure DataLoader with appropriate settings
    batch_size=10,
    max_batches=50
)

def get_related_items(item_id):
    """Fetches related items using DataLoader for optimized data access."""
    return dataloader.get(item_id) # returns a list of related objects efficiently

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