Kotlin Symbol Processing (KSP) en Kotlin: guía completa con ejemplos

1. ¿Qué es KSP y por qué usarla?

Kotlin Symbol Processing (KSP) es una biblioteca y un plugin del compilador para el lenguaje Kotlin, desarrollado por JetBrains. Su objetivo principal es ofrecer a los desarrolladores una API simple, rápida y confiable para analizar el código fuente de Kotlin durante la compilación y generar nuevo código a partir de él (generación de código). KSP es la alternativa directa al antiguo mecanismo javax.annotation.processing (Java Annotation Processing), que fue creado para Java y tiene varias limitaciones al trabajar con Kotlin.

¿Para qué sirve KSP? En el desarrollo moderno con Kotlin, a menudo es necesario generar código repetitivo de forma automática: clases DTO, mapeadores, implementaciones Parcelable, entidades Room, adaptadores Moshi y mucho más. KSP permite hacer esto en tiempo de compilación, sin usar reflexión en tiempo de ejecución, lo que mejora el rendimiento de la aplicación. A diferencia de KAPT (Kotlin Annotation Processing Tool), KSP trabaja directamente con el árbol AST de Kotlin, saltándose la etapa intermedia de Java, lo que proporciona una mejora de velocidad de 2 a 4 veces. KSP también ofrece mejor soporte para las construcciones más recientes del lenguaje Kotlin (funciones suspend, clases inline, clases value) y no requiere la generación de stubs de Java.

KSP es ideal para crear tus propias bibliotecas de generación de código, frameworks (similares a Dagger, Room, Glide) y herramientas de metaprogramación. Se utiliza activamente en el ecosistema Kotlin: Compose, Room, Moshi, Koin, Apollo GraphQL y muchas otras bibliotecas populares.

2. Instalación

KSP no se instala a través de pip o npm, sino mediante el sistema de compilación Gradle. Para un proyecto Kotlin, deberás agregar el plugin KSP y su versión correspondiente a la versión de Kotlin que estés usando.

Comando exacto para agregarlo en build.gradle.kts (proyecto raíz):

// build.gradle.kts (nivel raíz)
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 de la aplicación)
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 generar código
    ksp("com.example:my-processor:1.0.0") // tu procesador
}

Para Gradle Groovy (build.gradle):