Как да получите незабавни API за GraphQL на съществуващото си приложение Django

GraphQL API на съществуващото ви приложение Django

TL; DR

Ето темите, които ще разгледаме в тази статия, ако искате да скочите наоколо:

Защо GraphQL?

GraphQL е език за запитване на данни, разработен от Facebook. Той не е обвързан с конкретна база данни. Той предоставя начин клиентът да запитва от различни бази данни едновременно, като иска това, от което се нуждае. Той връща отговора във формата, поискан от клиента

Изградете GraphQL Server

Какви са различните подходи за изграждане на GraphQL сървър? Ще научим как Hasura GraphQL двигателят предоставя най-лесния начин да получите API на GraphQL във вашата съществуваща база данни.

Настройка на GraphQL двигателя

Ще преминем през инсталирането на Hasura GraphQL engine. След това ще изложим таблици над GraphQL API.

Осигуряване на GraphQL сървър

Справете се с миграцията

Така че нека започнем!

Защо GraphQL?

В типично приложение Django, всяко ново изискване за функция или промяна на схемата ще изисква добавяне или промяна на съществуващ изглед. Това може да има огромно влияние върху производителността на разработчиците. Това ще изисква актуализиране на кода на всички места, където се използва определен API.

Именно тук е полезен GraphQL. GraphQL е език за заявки за API. Тя резюмира множество източници на данни. Това дава възможност на разработчиците на приложения да изискват данни във необходимия им формат. Това прави, без да се изискват промени в задния API. Вместо да извикваме отделни крайни точки за получаване на данни, ние наричаме една крайна точка. Ние получаваме обратно цялата информация, която искаме, структурирана точно така, както я искаме.

Така че това може да ви накара да се замислите: как да получа API за GraphQL на съществуващото си приложение Django?

Изградете GraphQL сървър

За да изградите GraphQL сървър, всичко, което трябва да направите, е да определите схема. Схема е директория от типовете данни във вашето приложение. Функциите на Resolver казват на сървъра къде и как да извлекат данните за всеки тип данни.

Настоящите подходи включват писането му от нулата (схема, функции на резолюция) с помощта на инструменти като django-graphene.

В тази публикация ще използвам Hasura GraphQL engine, за да получа GraphQL API на съществуващото ми приложение Django, работещо локално. Ще стигнем до решение, както е показано на диаграмата по-долу.

Архитектура преди и след интегриране с Hasura GraphQL

Hasura GraphQL engine (HGE) ви дава незабавен графичен API в реално време на вашия съществуващ Postgres. HGE работи извън кутията с вашите съществуващи:

  • Postgres база данни - Свързва се със съществуващата ви база данни и предоставя GraphQL API на вашата база данни.
  • Система за удостоверяване - Свързва се със съществуващата система за удостоверяване, за да защити GraphQL API.
  • Миграционна система - Hasura GraphQL Engine не пречи на миграционната система на Django. Схемата може да се управлява отделно чрез models.py и django мигрират, докато и освен ако не променят схемата, проследявана от GraphQL Engine. Повече информация за това как Hasura GraphQL управлява състоянието на вашата схема можете да намерите тук.

Също така, той идва с изящна конзола (подобна на администратора на Django), която може да се използва за отстраняване на грешки в API на GraphQL.

Инсталация

Hasura GraphQL двигателят може да бъде инсталиран на Heroku с помощта на бутона по-долу:

Щракнете върху този бутон, за да разгърнете механизма на GraphQL в Heroku

или на всяка машина, която може да управлява Docker. Вижте секцията за начална работа за повече информация.

Инсталиране чрез докер и свързване към съществуващите Postgres

Преди да инсталирам Hasura GraphQL Engine, трябва да получа връзката Postgres за двигателя на Hasura GraphQL, за да се свържа с базата данни. Мога да получа връзката Postgres от връзката на приложението ми.py.

ДАТАБАЗИ = {
    'по подразбиране': {
        'ДВИГАТЕЛ': 'django.db.backends.postgresql',
        'NAME': 'postgres',
        'USER': 'postgres',
        'PASSWORD': 'SECUREPASSWORD',
        „HOST“: „172.17.0.1“,
        'PORT': '5432',
    }
}

URL адресът за връзка с базата данни ще стане:

Postgres: // Postgres: [email protected]: 5432 / Postgres

След като се стартира двигателят на Hasura GraphQL, посетете http: // localhost: 8080 отваря конзолата Hasura, както е посочено по-долу. Секцията "Данни" показва списък на непроследени таблици, присъстващи в базата данни, групирана по схема. Ако се чудите какво представляват непроследените таблици, насочете се към документите за повече информация.

Конзола на Hasura GraphQLHasura Console | Data Explorer

Горният скрийншот изброява таблиците, създадени от приложението Django, както са дефинирани в този models.py файл под непроследени таблици. Кликването върху бутона за добавяне се показва в списъка с проследявани таблици отляво. Излага ги да бъдат проверявани чрез API на GraphQL:

За да проверим дали всичко работи, нека се опитаме да намерим всички автори, налични в таблицата:

заявка {
  medium_author {
    документ за самоличност
    име
    интереси
  }
}

Отговорът от GraphQL двигателя е:

{
  "данни": {
    "medium_author": [
      {
        "име": "Картик",
        "id": 2,
        "интереси": "Крикет, музика, код"
      }
      {
        "name": "Втори автор",
        "id": 4,
        "интереси": "хокей"
      }
    ]
  }
}

Връзка на обект и масив

GraphQL engine анализира вашата схема и предлага взаимоотношения въз основа на чужди ключове, определени между таблиците.

Предложени външни ключови отношения

GraphQL engine автоматично предлага две взаимоотношения за всеки чужд ключ, който срещне.

  • Обектна връзка: 1: 1 връзка. Например, една статия ще има само един автор.
  • Връзка с масив: 1: много. Например един автор може да напише много статии.

В схемата на блога, mediumArticlesByauthorId е „отношение на масив“. Тя се основава на чуждия ключ medium_article :: author_id -> id в medium_article. mediumAuthorByAuthorId е „обектна връзка“, базирана на същия чужд ключ.

Когато проследяваме тези взаимоотношения, производната GraphQL схема съдържа имената на отношенията. И двете таблици, и връзката могат да бъдат заявени в една заявка:

Графична заявка с отношение на масивГрафична заявка с връзката на обекта

заверка

По подразбиране GraphQL двигателят е инсталиран в режим на разработка. Всички таблици / изгледи, които се проследяват от механизма на GraphQL, могат да бъдат преглеждани / актуализирани без проверки. Това е опасно и не се препоръчва в производствена среда.

Hasura ви позволява да дефинирате подробни контроли за достъп за всяко поле във вашата GraphQL схема, по принцип всяка таблица или изглед във вашата Postgres схема. Тези правила за контрол на достъп могат да използват динамични променливи, които влизат във всяка заявка. Вижте документите за повече информация.

GraphQL engine може да бъде защитен от директен достъп до него чрез конфигуриране на URL адрес на уебхоук. Графикът ще извика това, за да потвърди всяка заявка, освен ако искането не съдържа валиден ключ за достъп.

Архитектура на това как се случва заявката / отговора

Преди да защитим крайната точка на GraphQL с ключ за достъп и auth-кука (уебхоук URL), нека добавим просто правило за контрол на достъпа, използвайки конзолата Hasura, за да ограничим автора да извлича само неговите данни и да направи заявка с помощта на GraphQL Explorer.

Ето как изглежда правилото за контрол на достъпа за таблицата medium_author за роля = потребител.

Добавете контрол на достъпа към таблицата с автори

Създадох само разрешение за избор, но можете да конфигурирате за четирите типа операции (изберете, поставете, актуализирайте, изтрийте). Вижте документите за повече информация.

Нека запитваме от таблицата medium_author и да видим какъв е отговорът:

Тук, моля, имайте предвид, че x-hasura-user-id е зададен на "2", а x-hasura-ролята е на "потребител". Това са автентичните данни, които ще бъдат предадени от auth-кука в производствения режим (GraphQL двигателят стартира с ключ за достъп и auth-кука).

Secure GraphQL API

Да защитим механизма на GraphQL с ключ за достъп. Нека да конфигурираме auth-кука с манипулатора за удостоверяване, в случая приложението Django. Конфигурираната webhook ще бъде извикана от механизма на GraphQL. Webhook ще върне подходящаxx-hasura-роля и x-hasura-user-id.

Нека се опитаме отново да направим заявката и да видим какъв е отговорът:

Конфигурираната webhook отхвърля, тъй като заявката не е удостоверена. Нека се опитаме да влезете като потребител и да направим заявката с означението на автора. Системата Django auth разрешава бисквитките. Той добавя информацията за потребителя в контекста на заявката, която след това може да се използва от обработващия заявката.

За целта на този блог написах обикновен автентичен междинен софтуер. Той ще анализира разрешение: носител и ще го разреши в потребител на Django. Потребителят ще бъде добавен към контекста на заявката. Ето кодовия фрагмент на същия.

Влезте с потребител с id = 2Въпрос с влезлия потребител

Потребителят се удостоверява от webhook. Webhook връща съответния идентификатор на x-hasura-user и x-hasura-роля. GraphQL engine отговаря със съответните резултати, както е конфигурирано в правилата за достъп.

Миграционна система

Hasura GraphQL двигателят се предлага с мощни инструменти за миграция, вдъхновени от Rails, които ви помагат да следите промените, които правите във вашата схема. Докато използвате конзолата Hasura, Hasura CLI ще изплюе файлове за миграция за вас. Можете да ги поставите в контрол на версиите и дори да ги редактирате.

По подразбиране конзолата Hasura се обслужва от двигателя на GraphQL. Може да се използва за бързо изпробване на функциите, предоставени от механизма на GraphQL. Ако обаче изграждате сложно приложение или добавяте Hasura към съществуващото приложение или база данни, ще трябва да съхраните миграцията, за да гарантирате, че вашата итерация и CI / CD са гладки.

Настройвам

Инсталирайте hasura, като изпълните следната команда на вашия терминал, ако използвате Mac / Linux машина. В противен случай се насочете към нашите документи, за да инсталирате hasura в различни среди.

къдря -L https://cli.hasura.io/install.sh | удрям

Изпълнението на следната команда ще инициализира директория с конфигурационни файлове на hasura, конфигурирани да използват вашия GraphQL двигател.

$ hasura init - директория блог-hasura-приложение - endpoint http: // localhost: 8080 --access-key = mysecretkey
hasura init

Заменете стойността на крайната точка и ключа за достъп с подходящи стойности.

Деактивирайте миграцията

Тъй като Django се грижи за миграциите по подразбиране, миграцията на Hasura може да бъде деактивирана, като напишете конзолата hasura на вашия терминал. За да отворите конзолата Hasura, отворете Data -> Migrations (в лявата навигационна лента) и деактивирайте Allow postgres схеми.

Все още можем да съхраняваме метаданните Hasura само за да гарантираме, че приложението винаги е в състояние за възстановяване:

Преди да деактивирате миграциятаСлед деактивиране на миграцията

Експорт на метаданни

Експортирайте метаданните Hasura и ги съхранявайте в папката с миграции. Това ще гарантира, че системата ви винаги може да се възстанови от всяко нежелано състояние.

износ на метаданни на hasura

Горната команда ще експортира metadata.yaml и ще я съхранява в папката migrations.

Моля, уверете се, че таблиците / изгледите се създават / променят само чрез файла Django models.py, за да се избегне несъответствие.

Ако искате вместо това да използвате миграционна система Hasura, разгледайте документите за повече информация.

Hasura ви предоставя незабавни API за GraphQL API в реално време през която и да е база данни Postgres, без да се налага да пишете някакъв резервен код.

За тези от вас, които са нови в двигателя на Hasura GraphQL, това е добро място да започнете.