Англійська для рушія Hasura GraphQL

Вся мета Hasura - це створення GraphQL API безпосередньо з вашої схеми бази даних, що означає, що більшість помилок, які команда знаходить, не в написаному вручну коді розв’язувача - вони в дозволах, відносинах або налаштуваннях стеження. Назва цих специфічних для Hasura концепцій точно робить сеанси зневадження продуктивними, а не заплутаними.

Ключовий словник

** Таблиця з відстеженням ** — таблиця бази даних, яку Hasura було явно налаштовано для показу за допомогою автоматично створеного API GraphQL; таблиця без відстеження просто не з’ являється у схемі взагалі. “Нова колонка з’ явилась у базі даних, але не в API — виявляється, що сама таблиця ніколи не була відстежена в Hasura після запуску міграції.”

** Правило дозволів ** — правила доступу на рівні рядків і стовпчиків, визначені для кожної ролі (наприклад, user або admin ), які визначають, які рядки може повернути запит і які поля можна вибирати, вставляти або оновлювати. “Вада була не в нашому коді інтерфейсу — в правилі дозволів ролі user не було фільтра, тому він повертав рядки інших користувачів крім поточного користувача.”

** Відношення (об’ єкт / масив) ** — визначене посилання між двома таблицями (зазвичай, це похідне від зовнішнього ключа), яке надає змогу запиту GraphQL вкладати пов’ язані дані, відношення об’ єктів для одного пов’ язаного рядка і відношення масиву для багатьох. “Ми додали зв’язок масиву від authors до books, щоб один запит міг отримати автора разом з кожною книгою, яку він написав, замість того, щоб робити окремий запит на кожну книгу.”

** Віддалена схема ** — зовнішній GraphQL API, який Hasura вставляє у свою власну схему, дозволяючи клієнтам запитувати типи Hasura, підтримувані базою даних, і сторонні або нетипові типи служби в одному запиті. “Логіка рекомендацій знаходиться в окремій мікросервісі, тому ми додали її як віддалену схему — клієнти можуть запитувати продукцію і рекомендації разом, не знаючи, що в цьому беруть участь дві служби.”

** Hasura action ** — спосіб розширення автоматично створеного API Hasura за допомогою нетипової бізнес- логіки, визначеної як мутація GraphQL або запит, який Hasura пересилає до webhook, який ви керуєте, коли логіку не можна виразити як просту операцію з базою даних.

• “Надіслати привітальну електронну пошту неможливо автоматично, тому ми визначили її як дію, яка викликає наш власний webhook після вставки.” *

Звичайні фрази

• Чи ця таблиця насправді відстежується в Hasura, або вона просто існує в базі даних без виключення?»
• Чи є відсутні дані проблемою правила дозволів, чи самі відносини не налаштовані?»
• Чи повинно це бути об’єктне відношення або відношення масиву, враховуючи кардинальність тут?»
• «Чи це логіка, яку Hasura може автоматично генерувати, або нам потрібна нетипова дія з webhook?»
• «Цей тип походить з наших таблиць, або він насправді обслуговується через віддалену схему?»

Приклади висловлювань

Зневадження проблеми з правами доступу: “Користувачі бачили чернетки інших людей — правило дозволів для ролі user фільтрувало на published = true для читання, але не мало жодного фільтра на рівні рядка для вибору чернеток.”

Пояснення рішення щодо розробки схеми: “Ми додали зв’язок масиву від orders до order_items, щоб інтерфейс міг отримати повний запит в одному запиту, замість того, щоб клієнт робив N наступних запитів на елемент.”

Опис вибору архітектури у огляді:

• “Ми вставляємо в службу платежів віддалену схему, а не реплікуємо її дані у власні таблиці, оскільки стан платежу повинен залишатися авторитетним у цій службі.” *

Професійні поради

• Виразно вкажіть tracked, коли дані таблиці не з’ являються в API — це зазвичай перша річ, яку слід перевірити, і часто це справжня коренева причина.
• Назвіть конкретне ** правило дозволів ** і роль, що беруть участь при обговоренні помилки доступу — « права доступу неправильні » є набагато менш дієздатними, ніж « права вибору ролі user не мають фільтра »
• Розрізняти object і array relationships точно в перегляді схеми — вибір неправильної кардинальності раніше призводить до помилок при перегляді нульових і списків.
• Використовуйте ** action ** навмисно, коли пропонуєте нетипову логіку — це сигналізує про те, що ви вже виключили можливість виразити поведінку як просту операцію з базою даних, що є типовим і бажаним шляхом Hasura.

Практичні вправи

1. Поясніть, що означає « відстежувати » таблицю у Hasura.
2. Описати різницю між зв’ язком між об’ єктами і зв’ язком між масивами.
3. Напишіть речення, у якому поясните, коли ви могли б скористатися дією Hasura замість автоматично створеного CRUD.

На практиці: Навігація нюансів — оновлення комунікації навколо схеми Hasura

Будьмо чесними, коли ви створюєте з Hasura і GraphQL, технічний жаргон може здатися неймовірно точним. Це * є * точним, звичайно, але ця точність іноді може створити бар’ єр для ефективного спілкування, особливо для розробників, чия перша мова не є англійською. Крім простого розуміння визначення «схеми», «дозволів» і «зв’язків», мова йде про розуміння як ці терміни зазвичай використовуються в професійних ситуаціях - особливо при обговоренні змін або пошуку пояснень. Простий запит на зразок « Чи можете ви перевірити схему? » може не задовольнити вас. Замість цього, розгляньте можливість більш свідомо оформити ваш запит, щоб привернути увагу переглядача. Наприклад, сказати «Чи можете ви переглянути схему product, особливо зосередившись на відносинах між продуктами і категоріями, щоб переконатися, що ми правильно реалізували обмеження іноземного ключа?» негайно надає контекст і направляє їх зусилля.

Це стосується як розмов Slack, так і описів запитів на витягування. Уявіть, що під час перегляду коду ви отримуєте коментар: « Схема виглядає добре ». Це неймовірно нечітке слово! Більш продуктивною відповіддю буде: «Схема виглядає в цілому здоровою, але я турбуюся про відсутність явних обмежень NOT NULL на полі product_id в таблиці orders. Ми повинні розглянути можливість додавання цих елементів для поліпшення цілісності даних. Бачите, як ця фраза додає шар критичної оцінки і пропонує конкретну дію? Аналогічно, при написанні опису PR для змін, пов’язаних з віддаленими схемами Hasura - можливо, оновлення з’єднання з базою даних або зміна дозволів - не просто скажіть “Оновлена схема.” Замість цього, докладно * що * було оновлено: “Змінено схему users, щоб включити нові вимоги GDPR щодо зберігання даних, включаючи додавання поля часового штампу last_accessed і зміну пов’язаних дозволів для доступу до читання до цього поля.”

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

Ось простий приклад того, як ви можете скористатися hasura-cli для перевірки схеми, а потім обговорити вивід з членом команди:

hasura-cli introspect --schema <your_database_url>

За допомогою цієї команди буде створено представлення вашої схеми Hasura у форматі JSON. Після цього ви зможете поділитись цим файлом або навіть лише фрагментом його вмісту (наприклад, показати зв’ язки між таблицями), щоб полегшити обговорення можливих поліпшень або змін. Вивід може бути використаний як початкова точка для розмови і спільного вирішення проблем.