Введение в платформу Domain Graph Service (DGS)

1. Обзор

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

Netflix создал серверную структуру Domain Graph Service Framework (DGS), чтобы упростить задачу. В этом кратком руководстве мы рассмотрим ключевые функции DGS Framework. Мы увидим, как добавить этот фреймворк в наше приложение и проверим, как работают его основные аннотации. Чтобы узнать больше о самом GraphQL, ознакомьтесь с нашей статьей Introduction to GraphQL .

2. Платформа службы графа домена

Netflix DGS (Domain Graph Service) — это серверная структура GraphQL, написанная на Kotlin и основанная на Spring Boot. Он спроектирован так, чтобы иметь минимальные внешние зависимости, помимо среды Spring.

Фреймворк Netflix DGS использует основанную на аннотациях библиотеку GraphQL Java, созданную поверх Spring Boot. Помимо модели программирования на основе аннотаций, он предоставляет несколько полезных функций. Это позволяет генерировать исходный код из схем GraphQL. Подытожим некоторые ключевые особенности :

• Модель программирования Spring Boot на основе аннотаций
• Платформа тестирования для написания тестов запросов в виде модульных тестов
• Плагин Gradle/Maven Code Generation для создания типов из схемы
• Простая интеграция с GraphQL Federation.
• Интеграция со Spring Security
• Подписки GraphQL (WebSockets и SSE)
• Загрузка файлов
• Обработка ошибок
• Много точек расширения

3. Конфигурация

Во-первых, поскольку среда DGS основана на Spring Boot, давайте создадим приложение Spring Boot . Затем добавим в наш проект зависимость DGS :

<dependency>
    <groupId>com.netflix.graphql.dgs</groupId>
    <artifactId>graphql-dgs-spring-boot-starter</artifactId>
    <version>4.9.16</version>
</dependency>

4. Схема

4.1. Подходы к развитию

Платформа DGS поддерживает оба подхода к разработке — сначала схема и код. Но рекомендуемый подход — схема сначала, главным образом потому, что легче не отставать от изменений в модели данных. Schema-first указывает, что мы сначала определяем схему для службы GraphQL, а затем реализуем код, сопоставляя определения в схеме. Фреймворк по умолчанию выбирает любые файлы схемы в папке src/main/resources/schema .

4.2. Реализация

Давайте создадим простую схему GraphQL для нашего примера приложения, используя язык определения схем (SDL) :

type Query {
    albums(titleFilter: String): [Album]
}

type Album {
    title: String
    artist: String
    recordNo: Int
}

Эта схема позволяет запрашивать список альбомов и, при необходимости, фильтровать их по названию .

5. Основная аннотация

Начнем с создания класса Album , соответствующего нашей схеме:

public class Album {
    private final String title;
    private final String artist;
    private final Integer recordNo;

    public Album(String title, String artist, Integer recordNo) {
        this.title = title;
        this.recordNo = recordNo;
        this.artist = artist;
    }

    // standard getters
}

5.1. Сборщик данных

Сборщики данных отвечают за возврат данных для запроса. Аннотации @DgsQuery , @DgsMutation и @DgsSubscription — это сокращения для определения сборщиков данных для типов Query, Mutation и Subscription . Все упомянутые аннотации эквивалентны аннотации @DgsData . Мы можем использовать одну из этих аннотаций в методе Java, чтобы сделать этот метод сборщиком данных и определить тип с параметром.

5.2. Реализация

Итак, чтобы определить сборщик данных DGS, нам нужно создать метод запроса в классе @DgsComponent . В нашем примере мы хотим запросить список альбомов , поэтому давайте пометим метод @DgsQuery :

private final List<Album> albums = Arrays.asList(
  new Album("Rumours", "Fleetwood Mac", 20),
  new Album("What's Going On", "Marvin Gaye", 10), 
  new Album("Pet Sounds", "The Beach Boys", 12)
  );

@DgsQuery
public List<Album> albums(@InputArgument String titleFilter) {
    if (titleFilter == null) {
        return albums;
    }
    return albums.stream()
      .filter(s -> s.getTitle().contains(titleFilter))
      .collect(Collectors.toList());
}

Мы также отметили аргументы метода аннотацией @InputArgument . Эта аннотация будет использовать имя аргумента метода, чтобы сопоставить его с именем входного аргумента, отправленного в запросе.

6. Плагин CodeGen

DGS также поставляется с плагином для генерации кода для генерации кода Java или Kotlin из схемы GraphQL. Генерация кода обычно интегрируется со сборкой.

Плагин DGS Code Generation доступен для Gradle и Maven. Плагин генерирует код во время процесса сборки нашего проекта на основе файла схемы GraphQL нашей службы Domain Graph. Плагин может генерировать типы данных для типов, типов ввода, перечислений и интерфейсов, сборщиков выборочных данных и API запросов с безопасным типом. Существует также класс DgsConstants , содержащий имена типов и полей.

7. Тестирование

Удобный способ запроса нашего API — GraphiQL . GraphiQL — это редактор запросов, который поставляется вместе с инфраструктурой DGS. Давайте запустим наше приложение на порте Spring Boot по умолчанию и проверим URL-адрес http://localhost:8080/graphiql . Давайте попробуем выполнить следующий запрос и проверим результат:

{
    albums{
        title
    }
}

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

{
  "data": {
    "albums": [
      {
        "title": "Rumours"
      },
      {
        "title": "What's Going On"
      },
      {
        "title": "Pet Sounds"
      }
    ]
  }
}

8. Заключение

Domain Graph Service Framework — это простой и довольно привлекательный способ использования GraphQL. Он использует строительные блоки более высокого уровня для обработки выполнения запросов и тому подобного. Фреймворк DGS делает все это доступным с помощью удобной модели программирования Spring Boot. Этот фреймворк имеет несколько полезных функций, которые мы рассмотрим в статье.

Мы рассказали о настройке DGS в нашем приложении и рассмотрели некоторые его основные аннотации. Затем мы написали простое приложение, чтобы проверить, как создавать данные из схемы и запрашивать их. Наконец, мы протестировали наш API с помощью GraphiQL. Как всегда, пример можно найти на GitHub .