ТЕХНОЛОГИЯ ЭКСПЕДИА ГРУПП - ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ
Представляем GraphQL Kotlin Client
Новый легкий, безопасный для типов HTTP-клиент GraphQL
HTTP - наиболее распространенный способ взаимодействия с сервером GraphQL. Никаких специальных клиентов не требуется, поскольку вы просто отправляете HTTP-запрос POST с полем query в теле JSON. Хотя такой подход, безусловно, может сработать, он хрупок и легко может взорваться. Существует ряд продвинутых клиентов, доступных для разных языков, но до сих пор не было нативного решения Kotlin.
graphql-kotlin-client - это новый легкий и безопасный для типов HTTP-клиент GraphQL от Expedia Group ™ ️. Плагины Gradle и Maven для GraphQL Kotlin генерируют классы данных Kotlin на основе ваших запросов и проверяют их на соответствие целевой схеме GraphQL. graphql-kotlin-client легко настраивается, поскольку он использует HTTP-клиент Ktor для асинхронной связи с серверами GraphQL и поддерживает настройку для использования любых поддерживаемых движков и функций Ktor HTTP.
Конфигурация проекта
GraphQL Kotlin предоставляет плагины Gradle и Maven для автоматической генерации клиентского кода во время сборки. Создав классы данных, выполняйте их базовые операции GraphQL, используя graphql-kotlin-client зависимость времени выполнения.
Базовая build.gradle.kts конфигурация Gradle
Эквивалентная конфигурация Maven pom.xml
См. Проект graphql-kotlin-client-example для полных рабочих примеров проектов на основе Gradle и Maven.
Создание клиента GraphQL
По умолчанию плагины сборки GraphQL Kotlin генерируют клиентов GraphQL из всех .graphql файлов, расположенных в папке src/main/resources. Они также проверяют запросы на соответствие целевой схеме GraphQL.
Схема может быть предоставлена вручную, извлечена подключаемыми модулями посредством интроспекции (как настроено в приведенных выше примерах) или загружена непосредственно из пользовательской конечной точки SDL. См. Нашу документацию для получения более подробной информации о поддерживаемых Gradle задачах и Maven Mojos.
При создании запросов GraphQL всегда указывайте имя операции и соответственно называйте файлы. Каждый из ваших файлов запросов будет генерировать соответствующий файл Kotlin с классом, соответствующим вашему имени операции, который будет действовать как оболочка для всех соответствующих классов данных. Например, если задано HelloWorldQuery.graphql с HelloWorldQuery в качестве имени операции, плагины GraphQL Kotlin сгенерируют соответствующий HelloWorldQuery.kt файл с классом HelloWorldQuery в настроенном пакете.
Например, учитывая простую схему
И соответствующий HelloWorldQuery.graphql запрос
Плагины будут генерировать следующий клиентский код
Сгенерированные классы требуют экземпляра GraphQLClient и предоставляют единственный execute приостанавливаемый метод, который выполняет базовую операцию GraphQL с использованием предоставленного клиента.
Выполнение запросов
Ваши автоматически сгенерированные классы принимают экземпляр GraphQLClient, который представляет собой тонкую оболочку вокруг HTTP-клиента Ktor, которая обеспечивает правильную сериализацию и десериализацию ваших объектов GraphQL. GraphQLClient требует, чтобы целевой URL был указан, и по умолчанию используется полностью асинхронный неблокирующий механизм ввода-вывода на основе сопрограмм.
Возможности клиента
Поддержка полиморфных типов
GraphQL поддерживает полиморфные типы через союзы и интерфейсы, которые Kotlin представляет как маркеры и обычные интерфейсы. Чтобы сгенерированные объекты не были пустыми, запросы GraphQL, ссылающиеся на полиморфные типы, должны явно указывать все реализации.
Полиморфные запросы также должны явно запрашивать поле __typename. Джексон использует его, чтобы правильно различать разные реализации.
Данная схема примера
Мы можем запросить поле интерфейса как
Что сгенерирует следующую модель данных
Значения перечисления по умолчанию
Перечисления представляют собой предопределенные наборы значений. Добавление дополнительных значений перечисления может быть потенциально критическим изменением, поскольку ваши клиенты могут быть не в состоянии обрабатывать дополнительные значения. Клиент GraphQL Kotlin автоматически добавляет значение по умолчанию @JsonEnumDefaultValue __UNKNOWN_VALUE ко всем сгенерированным перечислениям в качестве меры защиты для обработки новых значений перечислений.
Автоматически созданная документация
Плагины сборки GraphQL Kotlin автоматически извлекают описания GraphQL запрашиваемых полей из целевой схемы и добавляют их как KDoc в соответствующие модели данных.
Учитывая простое определение объекта GraphQL
В результате будет создан соответствующий автоматически сгенерированный класс данных
Встроенная поддержка сопрограмм
Клиент GraphQL Kotlin - это тонкая оболочка поверх Ktor HTTP Client, которая обеспечивает полностью асинхронную связь через сопрограммы Kotlin. GraphQLClient предоставляет единственный execute метод, который
приостанавливает вашу операцию GraphQL до тех пор, пока не получит ответ, не блокируя базовый поток. Чтобы получать данные асинхронно и одновременно выполнять дополнительные вычисления, вы должны заключить выполнение вашего клиента в launch или async конструктор сопрограмм и явно await для их результатов.
Дополнительные сведения см. В документации сопрограмм Kotlin.
Настройка клиента
Настройка клиента HTTP Ktor
GraphQLClient использует HTTP-клиент Ktor для выполнения базовых запросов. Для клиентов можно настроить различные механизмы (по умолчанию C или IO на основе рутинга) и функции клиента HTTP. Создатели стиля Ktor DSL могут применять пользовательские конфигурации.
Подробнее см. Документация по HTTP-клиенту Ktor.
Кастомизация Джексона
GraphQLClient полагается на Джексона для обработки полиморфных типов и значений перечисления по умолчанию. Из-за необходимой логики для обработки вышеуказанного в настоящее время мы не поддерживаем другие библиотеки JSON.
Устаревшее использование полей
Плагины сборки автоматически завершают создание клиента, если какой-либо из указанных файлов запроса ссылается на устаревшие поля. Это гарантирует, что ваши клиенты должны будут явно отказаться от использования, указав параметр конфигурации allowDeprecatedFields.
Пользовательские скаляры GraphQL
По умолчанию, пользовательские скаляры GraphQL сериализуются и имеют псевдонимы типа aString. Плагины GraphQL Kotlin также поддерживают настраиваемую сериализацию на основе предоставленной конфигурации.
Для автоматического преобразования между пользовательским скалярным типом GraphQL UUID и java.util.UUID, нам сначала нужно создать наш собственный ScalarConverter.
А затем настройте плагин сборки, указав
- Пользовательское имя скаляра GraphQL
- Имя целевого класса
- Конвертер, который обеспечивает логику для сопоставления между типом GraphQL и Kotlin
Подробности см. В документации к плагинам Gradle и Maven.
Дальнейшее чтение
GraphQL Kotlin Client - это новый Kotlin облегченный типобезопасный HTTP-клиент GraphQL, который использует возможности Kotlin сопрограмм для полностью асинхронной связи. Типобезопасные модели данных удобно генерировать во время сборки с помощью предоставленных плагинов GraphQL Kotlin Gradle и Maven. Для получения дополнительных сведений о том, как использовать библиотеку, ознакомьтесь с документацией, доступной на страницах GitHub.
Мы также открыты для обратной связи, поэтому, пожалуйста, поднимите вопрос и начните обсуждение любых новых функций, которые вы хотели бы увидеть!
- Фото Скотта Гудвилла на Unsplash
