Руководство по GraphQL на простом английском

1656537982 rukovodstvo po graphql na prostom anglijskom

от Луиса Агилара

Все, что вам нужно знать о последнем модном слове, которое захватывает сцену разработки API штурмом.

1*PpKiiMujrwHszBHWoZDqPQ

TL; DR

GraphQL является языком запросов и время выполнения, которое мы можем использовать для создания и предоставления API в качестве строго типизированной схемы вместо сотен конечных точек REST. Ваши клиенты видят схему. Они пишут запрос, что они хотят. Они посылают его и получают именно те данные, которые они просили, и ничего больше.

Схема выглядит так:

Итак, если клиент хочет, чтобы пользователь с идентификатором 2, вместо того, чтобы делать a GET /api/v1/users/2они скорее отправят запрос вроде этого:

… и получить ответ так:

Почему REST должен следить за спиной и почему должен ты забота?

  1. Схема строго типизирована. Схема диктует, что id параметр должен быть целым числом. Если клиент отправляет user(id: “2”) Механизм GraphQL отклонит весь запрос.
  2. Клиенты выбирают то, что им нужно. Видите ли эти скобки после параметров запроса? Именно так наши клиенты рассказывают, какие поля они желают. Меньше полей = меньшие и более быстрые ответы.
  3. Это быстро. Невыбранные поля не будут обрабатываться, то есть меньше нагрузки на сервер.
  4. И главное, он гибок. Если клиенту требуется меньше полей от конечной точки, мы не создаем новую конечную точку или версию всего нашего API исключительно для этого. Они могут выбрать какие-либо поля, которые им нужны, и это бесплатно для нас.

И это все, что есть на самом деле. Никакой магии не происходит. Просто более удобный, гибкий и естественный способ создания вашего API.

Но какова жизнь без этих сочных основных концепций и милых, сладких примеров кода?

Большая пятерка

Прежде чем перейти к самому развлечению, мы должны иметь в виду некоторые понятия, иначе все остальное не будет иметь никакого смысла.

Не волнуйтесь – я скажу коротко.

Запрос

Член схемы, считывающий данные.

Мутация

Член схемы, изменяющий данные (например, создание, редактирование или удаление).

Схема

Однокорневое дерево с двумя основными узлами: один для запросов, а другой для мутаций.

Тип

Форма всего, что составляет схему. Возвращаемые запросом данные, поля этих данных, параметры, которые берет мутация, запросы и сами мутации — все имеет тип.

Типы состоят из полей, также имеющих тип.

Оба query и mutation начальные узлы имеют тип Query и Mutation соответственно. У них больше полей, users и user, и их тип также может иметь больше полей! Вот как вы структурируете свои данные API в дереве запросов.

Резолвер

Фактическая часть, соединяющая ваш код с вашей схемой. Резолверы – это фактические функции, которые решить значение отдельного поля в типе Дальше есть очень, очень barebones псевдопример того, как это работает – не возражайте.

Легко, да? Ну это все для теории, время для кода!

Абсолютно оригинальный и неиспользованный пример кода

Устали от классического примера кода модели пользователя? Я тоже нет! Ладно, это может быть скучным и неинтересным, но это хорошо для иллюстрации предыдущих концепций, поэтому давайте придерживаемся этого. До конца у нас будет API, клиенты смогут запрашивать пользователей, ролей и создавать новых пользователей.

1. Создайте сервер

Как уже упоминалось, GraphQL – это язык, и среда выполнения — мы все равно должны ее где-то поместить. Для этого примера он будет жить на сервере Express.

Итак, начнем:

  • Создайте новую папку.
  • Откройте терминал и cd в вашу папку.
  • Беги npm init && touch server.js
  • Беги npm i express --save чтобы, ну, установить ExpressJS.
  • Брось это в server.js:
  • Запустите сервер с помощью node server.js

Итак, у нас есть дом для нашего API GraphQL.

2. Добавьте щепотку GraphQL

Так просто, как:

  • Беги npm i graphql graphql-express --save
  • Редактировать server.js нравится это:

И вот почему важно пересмотреть концепции, прежде чем переходить к коду. Это простое приложение Hello World уже имеет много продолжается, но мы можем хотя бы получить представление.

Не волнуйтесь, вот аннотированная версия:

Подождите, мы жестко кодируем нашу схему с помощью огромной волшебной строчки? Не паникуйте – мы поговорим об этом позже.

Ладно, пора запустить Postman и отправить несколько запросов к нашему API GraphQL!

Хе, шучу…

На линии 46 мы включили GraphiQL (произносится «графический»,) встроенная полнофункциональная IDE для написания запросов. Теперь закройте Postman и перейдите к localhost:4000/graphql в вашем браузере.

1*kilXLXH_EGVuMulfFfiYPg
GraphiQL: лучшая вещь после налога IE7.

Что вы можете сделать с этим? Ну вот некоторые вещи, которые вы можете попробовать:

  • Просмотреть схему. Справа выберите Query корневой тип, чтобы увидеть его поля, типы возврата, документацию и т.д.
  • Пишите запросы. Слева введите запрос и обратите внимание, как редактор показывает автозаполнение и документацию во время работы:
  • Тестовые запросы. Если ваш запрос действителен, нажмите кнопку воспроизведения вверху и просмотрите результаты на средней панели.
1*DnfYdpMnUbIGAwshyLL5yw
ГрафикяQL: Каждый новый лучший друг

Но как быть с клиентами? Они могут использовать GraphяQL (или подобный инструмент существует множество) для создания и проверки их запросов. Затем отправьте их с помощью клиента GraphQL, такого как Apollo Boost – так же просто, как копирование и вставка!

3. Добавьте запрос в список пользователей

Ладно, Hello World все хорошо, но мы хотим делать больше, чем приветствовать людей. Добавим новый User введите и замените hello с users который вернет всех пользователей из фиктивного хранилища.

  • Редактировать server.js нравится это:
  • Возьмите user-repository.js файл отсюда и поместите его в свой локальный каталог.
  • Перезапустите сервер и обновите графикяQL редактор.
  • В своем запросе замените hello для users { id, login } и нажмите играть.
  • прибыль.
1*i6jTWR6tXLF_7ypl9hoK_g
Создание запроса: так просто, как 1–2–3.

с комментариями:

4. Добавьте запрос, чтобы получить одного пользователя по идентификатору

Теперь вы можете спросить: если запросы также являются полями определенного типа, почему бы не называть их полями? Чем они отличаются?

Запросы могут принимать настройки и использовать резольвер.

Самый простой способ увидеть это – сравнить с классами ООП. Хотя классы имеют поля и функции, типы GraphQL имеют поля и запросы.

Опять-таки, никакой магии.

Мы говорим, что user запрос принимает an id параметра и это то, что будет принимать его функция резольвера. О, также обратите внимание на ! знак, что означает, что параметр является обязательным – GraphQL убедится, что он предоставлен.

5. Замените Конструктор схем для определения вручную

Помните, как мы вызвали эту огромную волшебную нить, используемую для определения нашей схемы? Что ж, пора это исправить.

Ладно, в реальном приложении вы бы разделили свою схему *.graphql файлы. Затем можно добавить плагины подсветки синтаксиса и дополнение кода к своему редактору кода. Однако ручные определения предлагают лучшую интеграцию с остальным нашим кодом. Дополнительную информацию см. в данной статье.

Для этого мы будем использовать специализированные классы и помощники, предоставленные GraphQL:

Готово? Ладно, теперь примечание:

Таким образом, мы можем поместить определение типов в отдельные файлы, чтобы лучше организовать наш серверный код!

Как указано в примере, в этой нотации функция резольвера принимает следующие параметры:

  • rootрешен родительский объект, в данном случае пользователь.
  • argsаргументы, передаваемые запросом.
  • context, infoвыходят за рамки этого пособия.

6. Добавьте подзапрос для получения ролей пользователей

Мы научились определять основные запросы. Пора повысить это на ступеньку! Давайте добавим новое поле к User тип для предназначенных ему ролей. В традиционной архитектуре у нас возникнет соблазн создать новый запрос, как userRoles(userId: Int!): Role и назвать это день. Но у GraphQL все не так!

Мы должны подумать графики.

На языке графиков, чтобы получить роли пользователя, мы пришлем следующий запрос:

… и получить такой результат JSON:

Имеет смысл, правда? Давайте изменим схему.

Там мы можем получить роли пользователей сейчас. Обратите внимание, как мы использовали User экземпляр передается в качестве первого параметра распознавателя, чтобы получить идентификатор от родительского пользователя с развязкой.

1*o6VJ8MEkuRgfgPHZEx4hAg
Документация схемы – это ваша спина.

Преимущество подзапросов? GraphQL не решит проблему roles поле, если оно не выбрано в запросе.

Вы заметили ловушку с последним фрагментом кода?

Если мы спросим 100 пользователей и их роли, roles функция резольвера будет выполняться сторицей. Тогда, допустим, каждый пользователь имеет 10 ролей и каждая роль имеет поле подзапроса. Этот запрос будет выполнен 100*10 раз.

Это называется проблемой N+1.

Узнать, как это исправить, – это ваша домашняя задача! Но ходить одному опасно, и возьмите это:

Избегание n+1 запросов в GraphQL, в том числе в рамках подписок
Примечание: эта статья не будет иметь особого смысла, если вы не знаете основ GraphQL, замечательной технологии, которую мы используем…medium.com

7. Добавьте мутацию для создания нового пользователя

Как упоминалось ранее, мутации как мы изменяем данные в нашей схеме. Если мы хотим создать, отредактировать или удалить аккаунт пользователя, для этого нам понадобится мутация.

Мутации определяются почти так же, как запрос, и часто возвращают пораженные данные. То есть разница между ними только логична?

Точно.

Как уже упоминалось ранее, запросы также могут принимать параметры. Они возвращают только данные.

  • Отправьте следующий запрос с GraphяQL:
1*qq5k85ub7aQ3xB-siyUKUw
Опечатки: порча записей GIF с 1927 года

Вывод

Итак, надеемся, основы GraphQL понятны: настройка сервера, создание схемы (в обычной и сложной нотации) с типами, запросами и мутациями. Я использовал достаточно простой пример. Надеюсь, он хорошо послужил для ненавязчивой иллюстрации каждой концепции.

С этого момента вы должны расширить пример дополнительными материалами. Или вы можете создать совершенно новую кодовую базу для другого случая использования.

Чтобы начать, вот несколько вещей, которые вы можете попробовать:

  • Решение проблемы N+1 путем реализации загрузчиков данных.
  • Создайте мутации для проверки учетных данных пользователей, управления ролями пользователей и т.д.
  • Добавьте фактическую базу данных для питания ваших резольверов (MySQL, SQLite и т.д.)
  • Используйте серверную систему аутентификации, например OAuth, для проверки пользователей.
  • Создайте простую клиентскую программу, использующую клиент Apollo Boost для подключения к вашему серверу.
  • Перестройте пример с помощью TypeScript.

Возможности безграничны!

Получить исходный код

Весь пример размещен на GitHub. Просмотрите теги, чтобы увидеть постепенный прогресс кода.

ldiego08/workshops-graphql
GitHub – это место, где люди создают программное обеспечение. Более 28 миллионов человек используют GitHub, чтобы выявлять, расширять и вносить вклад в более…github.com

У вас есть вопросы, комментарии или что-нибудь, чем вы хотели бы поделиться? Найдите меня в Twitter как @ldiego08. Также не забудьте ?, поделиться и подписаться, если эта публикация была полезна!

Луис Агилар (@ldiego08) | Twitter
Сан-Хосе, Коста-Рика – автор научной фантастики, разработчик программного обеспечения @skillshare. twitter.com

Добавить комментарий

Ваш адрес email не будет опубликован.