Лекція 283: Встановлення та налаштування Spring GraphQL

Spring та його екосистема роблять розробку додатків ефективною, а інтеграція з GraphQL дозволяє використовувати сучасний, гнучкий і потужний спосіб роботи з даними. GraphQL надає єдиний endpoint для всіх операцій (запитів і мутацій), спрощуючи взаємодію клієнта і сервера. У поєднанні зі 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, яка повертає рядок. Як тільки схема готова, налаштуємо обробник запиту.

Налаштування endpoint

За замовчуванням Spring Boot GraphQL налаштовує endpoint /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. У наступних лекціях заглибимося у створення більш складних запитів, мутацій і підписок.