Интегрируйте GraphQL API в приложение iOS с минимальными усилиями — используя силу греческого бога Аполлона (шутка!)

Apollo — это современный кеширующий клиент GraphQL со строгой типизацией для iOS, написанный на Swift. Если вы все еще думаете, стоит ли использовать Apollo в своем проекте, аргументы в пользу его использования следующие:

  • Строгая типизация с codegen. Вам не нужно: анализировать JSON, передавать словари, вручную приводить объекты и писать модели самостоятельно. Клиент Apollo сделает это за вас.
  • Кэширование с гибкой настройкой. Вы можете кэшировать данные либо в памяти, либо с помощью SQLite. Apollo обеспечивает минимальное количество запросов, необходимых для поддержания вашего пользовательского интерфейса в актуальном состоянии с серверной частью. Кроме того, существует множество политик кэширования для настройки.
  • Просто и удобно 🛋. Если вы когда-либо делали сетевые запросы URLSession, у вас не будет сомнений в использовании Apollo.

Давай начнем!

Для статьи воспользуемся общедоступным API GraphQL — Fruits API. Предоставляет информацию о плодовых деревьях. Этот API достаточно прост и идеально подходит для изучения Apollo.

Шаг 1. Создайте проект Xcode и подключите Apollo

Файл › Новый › Проект… Думаю, вы поняли 😉.

После создания нового проекта следует подключить зависимость Apollo.

Установите его через любой менеджер пакетов по вашему выбору. Apollo поддерживает все три основных: SPM, CocoaPods или Carthage.

Я продолжу установку через SPM. Если вы выберете другое, вот инструкция для вас.

Файл › Добавить пакеты › вставьте эту ссылку:

Шаг 2. Загрузите схему и настройте этап сборки

Перейдите по ссылке на Игровую площадку Fruits API.

На правой вкладке нажмите СХЕМА, и вы сможете просмотреть типы и перечисления схемы API.

Нажмите «Загрузить» и добавьте загруженный файл в Xcode. Переименуйте его в schema.json для удобства.

И… пока никакой магии 😔. Перед использованием Apollo вы настроили этап сборки.

Используйте: +› Добавить новую фазу запуска сценария. Переименуйте его в Apollo (или любое другое имя, которое вам нравится). Поместите его перед этапом «Компиляция исходных кодов».

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

Последняя строка (независимо от того, какой менеджер пакетов вы использовали):

Он преобразует схему JSON в файл Swift с именем API.swift с типами данных и функциями, которые вы можете использовать без какой-либо дополнительной настройки.

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

Добавьте эту строку перед командой, которая преобразует схему в API.swift, упомянутую выше:

Соберите наш проект. И не получается…

Не волнуйтесь, мы почти здесь.

Для начала работы Apollo необходим хотя бы один запрос или мутация в проекте.

Шаг 3. Настройте запрос на игровой площадке API

Вернемся к игровой площадке Fruits API. Существует список мутаций и запросов, которые вы можете сделать:

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

Начните писать с запроса, затем имя, которое, по вашему мнению, хорошо описывает, какие данные получит этот запрос (я выберу GetAllFruits).

Подсказка 💡: не используйте запрос в конце имени запроса, так как Apollo автоматически добавит его при создании файла API.swift.

Снова откройте фигурные скобки и напишите все поля, которые вы хотите запросить из фруктового объекта.

Подсказка 💡: контроль + пробел для автодополнения

Я хочу запрашивать только названия фруктов. Скопируйте запрос с игровой площадки.

Шаг 4. Добавление запроса в Xcode

Создайте новый файл .graphql в Xcode, который будет содержать запрос.

Вставьте сюда запрос и создайте проект. Сборка удалась 🥳.

Все прошло успешно (если внимательно следовать инструкции).

Но где API.swift файл? Он уже находится в корневой папке проекта. И нам нужно только добавить его в Xcode (нужен только один раз, чтобы добавить его вручную).

Нажмите «Добавить файлы»… И произойдет волшебство. Вы получите весь код, необходимый для использования вашего API в классах и перечислениях Swift.

Для тех, кому интересно API.swift — это автоматически сгенерированный код на основе всех файлов .graphql в вашем проекте Xcode.

Подсказка 💡: не забудьте добавить автоматически сгенерированные файлы в .gitingore.

Шаг 5. Создайте клиент Apollo в коде и получите запрос

Пришло время использовать запрос.

Давайте перейдем к ViewController и напишем код:

Коротко о коде:

  1. Импорт Аполлона.
  2. Создайте экземпляр Apollo и укажите конечную точку (ссылку на ваш API) в качестве параметра.
  3. Используйте метод выборки клиента Apollo для создания запроса.
  4. Обработайте результат. В запросе может быть ошибка. Или случай, когда данные были получены, но произошла ошибка GraphQL.
  5. Покажите результат.

Мы успешно получили список фруктов.

Я надеюсь, что вы подготовите лучший пользовательский интерфейс, чем журнал консоли Xcode.

Должен признать, что мы не добавляли ни одного типа данных вручную, не использовали словарь и небезопасное приведение типов данных. Клиент Apollo сделал всю работу.

Еще одним преимуществом является то, что каждый раз, когда вы собираете проект, Apollo будет проверять, есть ли изменения на сервере. Если это так, он загрузит схему и сгенерирует новый файл API.swift. Это особенно удобно, когда вы находитесь на ранней стадии разработки и схема постоянно обновляется.

Надеюсь, вы узнали что-то новое и эта статья оказалась для вас полезной.

В моих следующих статьях я хотел бы рассказать, как выполнять мутации, использовать подписки и добавлять заголовки (а также токены) к запросам с помощью Apollo.

Если у вас есть что-то, что вы не знаете, как реализовать в Apollo, дайте мне знать, и я постараюсь вам помочь.

Спасибо за внимание!