Kotlin Symbol Processing (KSP) para Kotlin: guia completo com exemplos

1. O que é e para que serve

Kotlin Symbol Processing (KSP) é uma biblioteca e plugin de compilador para a linguagem Kotlin, desenvolvida pela JetBrains. Seu principal objetivo é fornecer aos desenvolvedores uma API simples, rápida e confiável para analisar o código-fonte Kotlin durante a compilação e gerar novo código a partir dele (geração de código). O KSP é uma alternativa direta ao antigo mecanismo javax.annotation.processing (Java Annotation Processing), que foi criado para Java e possui várias limitações ao trabalhar com Kotlin.

Para que serve o KSP? No desenvolvimento moderno com Kotlin, é comum precisar gerar automaticamente código repetitivo: classes DTO, mappers, implementações Parcelable, entidades Room, adapters Moshi e muito mais. O KSP permite fazer isso em tempo de compilação, sem reflexão em tempo de execução, aumentando a performance da aplicação. Diferente do KAPT (Kotlin Annotation Processing Tool), o KSP trabalha diretamente com a árvore AST do Kotlin, pulando a etapa intermediária do Java, o que resulta em um ganho de velocidade de 2 a 4 vezes. O KSP também oferece melhor suporte para construções modernas da linguagem Kotlin (funções suspend, classes inline, value classes) e não requer a geração de stubs Java.

O KSP é ideal para criar suas próprias bibliotecas de geração de código, frameworks (equivalentes a Dagger, Room, Glide) e ferramentas de metaprogramação. Ele é amplamente utilizado no ecossistema Kotlin: Compose, Room, Moshi, Koin, Apollo GraphQL e muitas outras bibliotecas populares.

2. Instalação

O KSP não é instalado via pip ou npm, mas sim através do sistema de build Gradle. Para um projeto Kotlin, você precisará adicionar o plugin KSP e sua versão correspondente à versão do Kotlin.

Comando exato para adicionar no build.gradle.kts (projeto raiz):

// build.gradle.kts (nível raiz)
plugins {
    id("org.jetbrains.kotlin.jvm") version "1.9.22" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

// build.gradle.kts (módulo da aplicação)
plugins {
    id("org.jetbrains.kotlin.jvm")
    id("com.google.devtools.ksp")
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.22")
    implementation("com.squareup:kotlinpoet:1.16.0") // para geração de código
    ksp("com.example:my-processor:1.0.0") // seu processador
}

Para Gradle Groovy (build.gradle):