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

Introdução: Por que GraphQL e Kotlin Formam uma Combinação Perfeita?

No desenvolvimento web moderno, escolher a ferramenta certa para criar uma API determina a velocidade de desenvolvimento e a facilidade de manutenção. GraphQL é uma linguagem de consulta que permite que os clientes solicitem apenas os dados de que precisam, eliminando os problemas de excesso e falta de dados inerentes ao REST. Kotlin, por sua vez, é uma linguagem moderna, concisa e segura, ideal para desenvolvimento backend, especialmente em conjunto com o Spring Boot.

Neste tutorial, vamos construir na prática uma API GraphQL completa em Kotlin. Você aprenderá como configurar um servidor, definir um schema, implementar queries e mutations, e testar a API finalizada. Ao final do artigo, você terá um projeto funcional que pode ser usado como base para suas aplicações.

1. Configuração do Projeto e Dependências

Primeiro, vamos criar um novo projeto Spring Boot com suporte a GraphQL. Usaremos o Spring for GraphQL — a integração oficial que torna o trabalho o mais simples possível.

1.1. Criando o Projeto

Você pode usar o Spring Initializr ou qualquer IDE (IntelliJ IDEA). Adicione as seguintes dependências:

• Spring Web
• Spring for GraphQL
• Spring Data JPA
• Banco de Dados H2 (para simplicidade)

O arquivo build.gradle.kts deve conter as seguintes linhas:

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("org.springframework.boot:spring-boot-starter-data-jpa")    runtimeOnly("com.h2database:h2")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.2. Configuração

Vamos criar uma entidade Book simples e um repositório para trabalhar com o banco de dados.

// Book.kt@Entitydata class Book(    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)    val id: Long = 0,    val title: String,    val author: String,    val year: Int)

// BookRepository.ktinterface BookRepository : JpaRepository<Book, Long>

2. Criando o Schema GraphQL e o Controller

GraphQL usa tipagem estrita. O schema define quais dados estão disponíveis e como eles podem ser consultados. No Spring for GraphQL, o schema pode ser descrito usando anotações.

2.1. Definindo o Schema via Código

Vamos criar uma classe controller que manipulará as consultas GraphQL. Use a anotação @QueryMapping para leitura de dados e @MutationMapping para modificações.

// BookController.kt@Controllerclass BookController(private val repository: BookRepository) {

    @QueryMapping    fun allBooks(): List<Book> = repository.findAll()

    @QueryMapping    fun bookById(@Argument id: Long): Book? = repository.findById(id).orElse(null)

    @MutationMapping    fun addBook(@Argument title: String, @Argument author: String, @Argument year: Int): Book {        val book = Book(title = title, author = author, year = year)        return repository.save(book)    }

    @MutationMapping    fun deleteBook(@Argument id: Long): Boolean {        if (repository.existsById(id)) {            repository.deleteById(id)            return true        }        return false    }}

2.2. Alternativa: Arquivo .graphqls de Schema

Você também pode definir o schema em um arquivo schema.graphqls separado na pasta resources/graphql:

type Query {    allBooks: [Book]    bookById(id: ID!): Book}

type Mutation {    addBook(title: String!, author: String!, year: Int!): Book    deleteBook(id: ID!): Boolean}

type Book {    id: ID!    title: S