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

Луис Агилар

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

TL; доктор

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

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

Итак, если клиент хочет пользователя с идентификатором 2, а не делать Get/API/V1/пользователи/2 , они предпочли бы отправить такое запрос:

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

Почему следует отдохнуть следить за спиной и зачем Вы уход?

1. Схема сильно набирается. Схема диктует, что ID Параметр должен быть целым числом. Если клиент отправляет Пользователь (ID: «2») Вместо этого двигатель Graphql отклонит весь запрос.
2. Клиенты выбирают то, что им нужно. Смотрите эти брекеты после параметров запроса? Вот как наши клиенты говорят, какие поля они хотят. Меньше и быстрее ответов.
3. Это быстро. Поля, не выбранные, не будут обработаны, что означает меньше нагрузки на сервере.
4. И самое главное, это гибко. Если клиент нуждается меньше полей с конечной точки, мы не создаем новую конечную точку или версию нашу целую API исключительно для этого необходимости. Они могут выбрать те поля, которые им нужны, и это бесплатно для нас.

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

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

Большое пять

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

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

Запрос

Член схемы, который читает данные.

Мутация

Член схемы, который модифицирует данные (как в создании, редактировании или удалении.)

Схема

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

Тип

Форма всего, что составляют схему. Данные, возвращаемые запросом, полями этих данных, параметры, предпринятые мутацией, запросами и самими мутациями – все имеют тип.

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

Оба Запрос и Мутация Начальные узлы имеют тип Запрос и Мутация соответственно. У них есть больше полей, Пользователи и Пользователь И их тип также может иметь больше полей! Вот как вы структурируете свои данные API в запросное дерево.

Резолюст

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

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

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

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

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

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

Так что давайте начнем:

• Создать новую папку.
• Откройте терминал и CD к вашей папке.
• Беги NPM Init && Touch Server.js
• Беги NPM I Express --save Для, ну установить Expressjs.
• Бросить это в Server.js :

• Запустите сервер с Node Server.js.

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

2. Добавить щепотка графаql

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

• Беги NPM I GraphQl GraphQl-Express --save
• Редактировать Server.js нравится:

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

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

Хорошо, время выстрелить почтальон и отправить некоторые запросы на нашу API Graphql!

Хе, просто шучу …

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

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

• Просмотр схемы. Вправо, выберите Запрос Тип корня, чтобы увидеть его поля, типы возврата, документацию и т. Д.
• Написать запросы. Влево, введите следующий запрос и обратите внимание, как редактор отображает автозаполнение и документацию, как вы идете:

• Тестовые запросы. Если ваш запрос действителен, нажмите кнопку воспроизведения сверху и посмотрите результаты на средней панели.

Но как насчет клиентов? Они могут использовать график Я QL (или аналогичный инструмент – есть тонны) для создания и проверки их запросов. Затем отправьте их через использование клиента GraphQL, такое как APOLLO BOOST – так же просто, как копирование и вставка!

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

Хорошо, Hello World в порядке и все, но мы хотим сделать больше, чем приветствие людей. Давайте добавим новый Пользователь Тип и заменить Привет с Пользователи Что вернет всех пользователей из фиктивного хранилища.

• Редактировать Server.js нравится:

• Хватает user-repository.js Файл из здесь и поместите его в свой локальный каталог.
• Перезапустите свой сервер и обновите график Я Ql редактор.
• В вашем запросе замените Привет для Пользователи {ID, логин} и ударить играть.
• Выгода.

Аннотирован:

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

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

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

Самый простой способ увидеть, что это состоит в том, чтобы сравнить его с классами OOP. В то время как классы имеют поля и функции, типа GraphQL имеют поля и запросы.

• Редактировать Server.js с участием:

Опять не волшебство.

Мы говорим Пользователь Запрос берет ID Параметр, и это то, что займет его функция Resolver. О, также обратите внимание на Действительно Знак, означающий параметр требуется-GraphQL убедитесь, что он предоставлен.

5. Заменить строитель схемы с помощью руководных определений

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

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

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

Выполнено? Хорошо, сейчас аннотировано:

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

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

• root – разрешенный родительский объект, в этом случае пользователь.
• args – Аргументы прошли запрос.
• контекст , Информация – Вне сферы этого руководства.

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

До сих пор мы научились определять основные запросы. Время превратить его на ступеньку! Давайте добавим новое поле в Пользователь Тип для его назначенных ролей. В традиционной архитектуре мы бы соблазнены создать новый запрос, как UseRolls (userid: int!): Роль и назовите это в день. Но это не то, как все работает в Graphql!

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

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

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

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

• Редактировать Server.js с участием:

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

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

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

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

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

Выяснить, как исправить это ваша домашняя работа! Но опасно идти один, поэтому возьми это:

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

7. Добавьте мутацию, чтобы создать новый пользователь

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

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

Точно.

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

• Редактировать Server.js с участием:

• Отправить следующий запрос из графа Я QL:

• Выгода.

Заключение

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

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

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

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

Возможности бесконечны!

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

Весь пример размещен в Github. Просматривать Теги увидеть постепенное прогрессирование кода.

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

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

Оригинал: “https://www.freecodecamp.org/news/a-beginners-guide-to-graphql-60e43b0a41f5/”