GraphQL API com Kotlin: tutorial prático passo a passo

Introdução: Por que GraphQL e Kotlin?

No mundo do desenvolvimento web moderno, escolher a abordagem correta para criar uma API pode determinar o sucesso de todo o projeto. O GraphQL, desenvolvido pelo Facebook, oferece uma alternativa flexível ao REST, permitindo que os clientes solicitem apenas os dados de que realmente precisam. E o Kotlin, uma linguagem de programação moderna para a JVM, adiciona a isso concisão, segurança contra nulos e suporte poderoso para corrotinas.

Neste tutorial, criaremos na prática uma API GraphQL completa usando Kotlin e o framework graphql-kotlin-spring-server. Você aprenderá como configurar o servidor, definir o esquema de dados, escrever resolvers e testar a API. Ao final do artigo, você será capaz de implementar GraphQL em seus próprios projetos em Kotlin.

1. Configuração do projeto e dependências

Para começar, criaremos um novo projeto Spring Boot com suporte a GraphQL. Usaremos o Gradle como sistema de build.

1.1. Criando a estrutura básica

Crie um novo projeto no IntelliJ IDEA ou através do Spring Initializr. Adicione as seguintes dependências no build.gradle.kts:

plugins {\n    id("org.springframework.boot") version "3.2.0"\n    id("io.spring.dependency-management") version "1.1.4"\n    kotlin("jvm") version "1.9.21"\n    kotlin("plugin.spring") version "1.9.21"\n}\n\ndependencies {\n    implementation("org.springframework.boot:spring-boot-starter-web")\n    implementation("com.expediagroup:graphql-kotlin-spring-server:7.0.1")\n    implementation("org.jetbrains.kotlin:kotlin-reflect")\n    implementation("org.jetbrains.kotlin:kotlin-stdlib")\n    testImplementation("org.springframework.boot:spring-boot-starter-test")\n}

1.2. Configuração da aplicação

Crie o arquivo application.yml em src/main/resources:

server:\n  port: 8080\n\ngraphql:\n  packages:\n    - "com.example.graphqldemo"\n  schema:\n    introspection-enabled: true\n    exception-handlers-enabled: true

Esta é a configuração básica. O parâmetro introspection-enabled: true permite usar o GraphiQL para testes.

2. Definição do esquema GraphQL

No graphql-kotlin, o esquema é construído automaticamente com base nas suas classes de dados (data classes). Esta é uma das principais vantagens — não é necessário escrever um arquivo SDL separado.

2.1. Criando o modelo de dados

Suponha que estamos criando uma API para uma biblioteca de livros. Vamos definir os modelos:

package com.example.graphqldemo.model\n\ndata class Book(\n    val id: String,\n    val title: String,\n    val author: Author,\n    val year: Int,\n    val genre: String\n)\n\ndata class Author(\n    val id: String,\n    val name: String,\n    val books: List<Book> = emptyList()\n)\n\n// Tipos de entrada para mutações\ndata class BookInput(\n    val title: String,\n    val authorId: String,\n    val year: Int,\n    val genre: String\n)

2.2. Serviço para manipulação de dados

Vamos criar um serviço simples em memória que armazenará os dados:

package com.example.graphqldemo.service\n\nimport com.example.graphqldemo.model.Author\nimport com.example.graphqldemo.model.Book\nimport com.example.graphqldemo.model.BookInput\nimport org.springframework.stereotype.Service\nimport java.util.UUID\n\n@Service\nclass LibraryService {\n    private val authors = mutableListOf(\n        Author("1", "J.K. Rowling"),\n        Author("2", "George Orwell")\n    )\n    private val books = mutableListOf(\n        Book("1", "Harry Potter e a Pedra Filosofal", authors[0], 1997, "Fantasia"),\n        Book("2", "1984", authors[1], 1949, "Distopia")\n    )\n\n    fun getBooks(): List<Book> = books\n    fun getBookById(id: String): Book? = books.find { it.id == id }\n    fun getAuthors(): List<Author> = authors\n    fun addBook(input: BookInput): Book {\n        val author = authors.fin