Aplicando el plugin de Kotlin para Gradle

Todo proyecto Kotlin/JVM empieza con una línea decisiva dentro del bloque plugins {}: kotlin("jvm") version "2.1.10". La llamada kotlin(...) es un ayudante que provee el Kotlin DSL de Gradle y que se expande al id completo del plugin org.jetbrains.kotlin.jvm. Aplicarlo es lo que le enseña a Gradle a entender los archivos .kt; sin él, Gradle solo conoce Java, los recursos y los demás plugins que hayas declarado. La cadena de versión fija el compilador y el toolchain de Kotlin, de modo que todos los que construyan el proyecto, y tu servidor de CI, compilen exactamente con la misma versión de Kotlin.

Aplicar el plugin hace tres cosas importantes en el día a día. Primero, registra los source sets de Kotlin, así src/main/kotlin y src/test/kotlin se vuelven directorios de código compilables junto a los de Java. Segundo, crea las tareas de compilación: compileKotlin para el código principal y compileTestKotlin para las pruebas, y las conecta al ciclo de vida estándar para que al ejecutar build o assemble se invoque el compilador de Kotlin automáticamente. Tercero, agrega por ti la biblioteca estándar de Kotlin (kotlin-stdlib). Desde Kotlin 1.4+ la stdlib se aplica por defecto, así que no escribes una dependencia explícita para ella: funciones como let, apply, listOf y toda la API de colecciones vienen incluidas automáticamente.

Configuras el compilador mediante la extensión kotlin { } que aporta el plugin. La forma moderna e idiomática de elegir el target de bytecode es el toolchain de JVM: kotlin { jvmToolchain(21) } le indica a Gradle contra qué JDK compilar y ejecutar. Si ese JDK no está instalado localmente, Gradle puede aprovisionarlo automáticamente, pero solo cuando hay configurado un resolver de toolchains, como el plugin Foojay (id("org.gradle.toolchains.foojay-resolver-convention")) declarado en settings.gradle.kts. Este enfoque de toolchain reemplaza enfoques antiguos y frágiles que fijaban sourceCompatibility a mano o configuraban jvmTarget directamente, y garantiza la misma versión de Java en cada máquina que toque el build.

Más allá del plugin jvm principal, JetBrains publica plugins de compilador complementarios que se aplican igual mediante el ayudante kotlin(...). kotlin("plugin.serialization") habilita kotlinx.serialization, generando serializadores eficientes en tiempo de compilación para cualquier clase marcada con @Serializable; aún debes agregar el runtime kotlinx-serialization-json como dependencia, pero es el plugin lo que hace que @Serializable realmente funcione. kotlin("plugin.spring") es el plugin all-open preconfigurado para Spring: hace automáticamente open las clases anotadas con @Component, @Service, @Configuration y similares, porque las clases de Kotlin son final por defecto y Spring necesita crear subclases proxy. Existe además kotlin("plugin.jpa") (el plugin no-arg) para entidades de Hibernate/JPA.

Cuando aplicas varios plugins de Kotlin, declara la versión solo una vez en la primera línea kotlin(...) y omítela en las demás: los plugins complementarios de Kotlin heredan la versión del plugin principal, así que repetirla es redundante y arriesga inconsistencias. En un build multi-módulo el patrón más limpio es poner la versión en el proyecto raíz (a menudo con apply false) o, mejor aún, en un catálogo de versiones de Gradle (gradle/libs.versions.toml) para que las versiones de plugins y librerías vivan en un solo lugar. Esta lección es de lectura: los builds de Gradle no se ejecutan en el editor del navegador, así que concéntrate en reconocer qué aporta cada línea más que en ejecutarla.

Un modelo mental rápido: settings.gradle.kts nombra el build y sus módulos y es donde centralizas los repositorios de plugins (y el resolver de toolchains); build.gradle.kts aplica plugins y declara dependencias; y libs.versions.toml es el catálogo opcional pero recomendado que te da accesores con tipos como alias(libs.plugins.kotlin.jvm). Domina estos tres archivos y podrás leer casi cualquier proyecto Kotlin/JVM moderno de un vistazo.

plugins {
    // Adds Kotlin/JVM support: compileKotlin task + stdlib, version pins the compiler
    kotlin("jvm") version "2.1.10"
}

repositories {
    mavenCentral()
}

kotlin {
    // Modern way to pick the JDK to compile/run against
    // (Gradle can download it if a toolchain resolver is configured in settings.gradle.kts)
    jvmToolchain(21)
}

dependencies {
    // No kotlin-stdlib line needed — the plugin adds it automatically since Kotlin 1.4
    testImplementation(kotlin("test"))
}

plugins {
    kotlin("jvm") version "2.1.10"          // version declared once here
    kotlin("plugin.serialization")          // enables @Serializable (version inherited)
    kotlin("plugin.spring")                  // all-open: opens @Component/@Service classes
}

dependencies {
    // The serialization plugin needs its runtime to actually (de)serialize JSON
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
}

# gradle/libs.versions.toml — central version catalog
[versions]
kotlin = "2.1.10"

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

# then in build.gradle.kts:
# plugins {
#     alias(libs.plugins.kotlin.jvm)
#     alias(libs.plugins.kotlin.serialization)
# }