Лекция 283: Установка и настройка Spring GraphQL

Spring и его экосистема делают разработку приложений эффективной, а интеграция с GraphQL позволяет использовать современный, гибкий и мощный способ работы с данными. GraphQL предоставляет единый эндпоинт для всех операций (запросов и мутаций), упрощая взаимодействие клиента и сервера. В сочетании с Spring мы получаем мощный инструмент для разработки API, который может легко заменить или дополнить REST.

1. Установка Spring GraphQL: создаём проект

Давайте начнём с настройки нового Spring Boot проекта, поддерживающего GraphQL. Мы воспользуемся Spring Initializr, который позволит быстро собрать подходящий шаблон проекта.

Использование Spring Initializr

1. Откройте Spring Initializr.
2. Укажите:
   • Project: Maven (вы также можете использовать Gradle, если предпочитаете).
   • Language: Java.
   • Spring Boot: версия 2.7.0 или выше (GraphQL поддерживается с 2.7.0).
3. Добавьте необходимые зависимости:
   • Spring Web
   • Spring Boot Starter GraphQL
   • Spring Boot DevTools (для быстрой перезагрузки приложения — крайне полезно для разработки).
4. Скачайте шаблон проекта и импортируйте его в свою любимую IDE (IntelliJ IDEA, Eclipse и т.д.).

Пример pom.xml

Ваш файл pom.xml должен выглядеть примерно так:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.graphql-java-kickstart</groupId>
        <artifactId>graphql-spring-boot-starter</artifactId>
        <version>12.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-graphql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
</dependencies>

Всё готово для начала работы! Давайте перейдём к настройке GraphQL-сервера.

2. Настройка GraphQL-сервера

GraphQL требует описания схемы и маршрутов. Spring Boot упрощает этот процесс, автоматически подключая схему и точку входа для GraphQL.

Папка для схемы

Создайте папку graphql в директории src/main/resources. В этой директории мы будем хранить схемы GraphQL.

Определяем первую схему

Создайте файл schema.graphqls в папке graphql. Это файл, где мы опишем типы и доступные операции. Вот что может быть внутри для начала:

type Query {
    hello: String
}

Здесь представлена простая операция hello, которая возвращает строку. Как только схема будет готова, мы настроим обработчик запроса.

Настройка эндпоинта

По умолчанию Spring Boot GraphQL настраивает эндпоинт /graphql для обработки всех запросов GraphQL. Чтобы это проверить, запустите своё приложение, а затем откройте в браузере http://localhost:8080/graphql.

На данном этапе вы увидите, что наш сервер уже готов к взаимодействию. Теперь давайте перейдём к обработке нашего первого запроса.

3. Создание резолверов для Query

GraphQL использует "резолверы" для связи операций (запросов, мутаций) с логикой Java-кода. Для нашего первого запроса hello, мы создадим резолвер.

Создаём резолвер

Добавьте новый класс в ваш проект:

package com.example.graphql;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

    @QueryMapping
    public String hello() {
        return "Привет из GraphQL!";
    }
}

Здесь:

1. @Controller — сообщает Spring, что этот класс будет обрабатывать запросы.
2. @QueryMapping — связывает метод с нашим запросом hello в схеме.

4. Тестируем GraphQL-запросы

Мы можем протестировать запросы с использованием встроенного инструмента GraphQL — GraphiQL, который уже интегрирован в Spring Boot.

1. Запустите приложение.
2. Перейдите в браузере по адресу: http://localhost:8080/graphiql.
3. Вставьте следующий запрос:

   query {
       hello
   }
   

Если всё сделано правильно, вы увидите:

{
  "data": {
    "hello": "Привет из GraphQL!"
  }
}

Поздравляю! Вы только что создали своё первое приложение с GraphQL!

5. Настройки IDE для работы с GraphQL

Плагин для IntelliJ IDEA

Если вы используете IntelliJ IDEA, отличный инструмент для работы с GraphQL — это плагин GraphQL, доступный в JetBrains Marketplace. Он помогает:

• Автоматически проверять вашу GraphQL-схему.
• Подсвечивать ошибки и автодополнять запросы.
• Тестировать запросы прямо из IDE.

Установка:

1. Откройте настройки IntelliJ IDEA: File > Settings > Plugins.
2. Найдите плагин GraphQL и установите его.
3. Перезагрузите IDE.

Теперь вы можете легко редактировать и тестировать свои схемы и запросы.

6. Продвинутая настройка GraphQL-сервера

GraphQL-сервер Spring Boot поддерживает конфигурацию через application.properties или application.yml. Например:

spring.graphql.graphiql.enabled=true
spring.graphql.schema.printer.enabled=true

Здесь:

• spring.graphql.graphiql.enabled=true включает встроенный GraphiQL интерфейс (по умолчанию включён).
• spring.graphql.schema.printer.enabled=true позволяет печатать вашу схему в логах при старте приложения (удобно для проверки).

7. Основные ошибки и пути их исправления

• Ошибка: "No schema found". Убедитесь, что файл вашей схемы schema.graphqls находится в папке src/main/resources/graphql — это стандартный путь для GraphQL схем в Spring Boot.
• Ошибка: "Query [name] not found". Если запрос из схемы не находит резолвер, убедитесь, что названия совпадают, и метод помечен аннотацией @QueryMapping.
• Ошибка: "Circular dependency". Такое может случиться при использовании нескольких бинов с комплексной зависимостью. Для решения попробуйте аннотации @Lazy или пересмотрите архитектуру.

Теперь вы готовы к более сложным схемам, запросам и мутациям! Мы сделали первый шаг в интеграции GraphQL с Spring Boot. В следующих лекциях мы углубимся в создание более сложных запросов, мутаций и подписок.