GraphQL API com Kotlin: tutorial passo a passo para iniciantes

Introdução: Por que GraphQL e Kotlin são a combinação perfeita para APIs modernas

O desenvolvimento web moderno exige APIs flexíveis e eficientes. O REST, por muito tempo o padrão, frequentemente leva ao problema de over-fetching (quando o servidor envia mais dados do que o necessário) ou under-fetching (quando são necessárias várias requisições para obter informações completas). O GraphQL resolve esses problemas permitindo que o cliente solicite apenas os dados necessários em uma única requisição.

Kotlin, por sua vez, é uma linguagem moderna, concisa e type-safe, ideal para criar serviços backend robustos. Graças à biblioteca graphql-kotlin do Expedia Group, criar uma API GraphQL em Kotlin se torna simples e intuitivo. Neste tutorial, criaremos passo a passo uma API GraphQL completa para gerenciar uma lista de livros.

O que você aprenderá:

• Como configurar um projeto Spring Boot com suporte a GraphQL.
• Como definir um schema GraphQL usando classes Kotlin.
• Como implementar Queries e Mutations.
• Como testar a API através da IDE GraphiQL integrada.

Passo 1: Configuração do projeto e dependências

Para começar, criaremos um novo projeto Spring Boot. Usaremos Gradle (Kotlin DSL) — o padrão para projetos Kotlin modernos.

1.1. Criando o projeto

Você pode usar o Spring Initializr ou criar a estrutura manualmente. Precisaremos das seguintes dependências:

• Spring Web — para iniciar o servidor HTTP.
• Spring Boot Starter GraphQL — a integração principal.
• Kotlin Reflection — para o funcionamento da biblioteca graphql-kotlin.

1.2. Arquivo build.gradle.kts

plugins {    id("org.springframework.boot") version "3.2.0"    id("io.spring.dependency-management") version "1.1.4"    kotlin("jvm") version "1.9.20"    kotlin("plugin.spring") version "1.9.20"}

group = "com.example"version = "0.0.1-SNAPSHOT"

java {    toolchain {        languageVersion = JavaLanguageVersion.of(17)    }}

repositories {    mavenCentral()}

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("com.expediagroup:graphql-kotlin-spring-server:7.0.1")    implementation("org.jetbrains.kotlin:kotlin-reflect")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.3. Configuração application.yml

spring:  graphql:    graphiql:      enabled: true  # Habilita a IDE integrada para testes    schema:      locations: "classpath:graphql/**/"server:  port: 8080

Passo 2: Definição do schema e modelo de dados

No GraphQL, o schema é o contrato entre cliente e servidor. A biblioteca graphql-kotlin permite definir o schema automaticamente com base nas classes Kotlin (abordagem code-first). Isso elimina a necessidade de escrever arquivos .graphqls manualmente.

2.1. Criando o modelo de dados

Criaremos um modelo simples Book e um repositório para armazenar dados em memória.

package com.example.graphqlkotlin.model

data class Book(    val id: String,    val title: String,    val author: String,    val year: Int)

2.2. Repositório (in-memory)

package com.example.graphqlkotlin.repository

import com.example.graphqlkotlin.model.Bookimport org.springframework.stereotype.Repositoryimport java.util.concurrent.ConcurrentHashMap

@Repositoryclass BookRepository {    private val books = ConcurrentHashMap(        mapOf(            "1" to Book("1", "Guerra e Paz", "Liev Tolstói", 1869),            "2" to Book("2", "Crime e Castigo", "Fiódor Dostoiévski", 1866)        )    )}