Desestructurado: del orden peligroso al nombre seguro

El desestructurado es la única característica de las data class que se apoya en un contrato invisible y frágil: el orden de declaración de las propiedades. Durante quince años, cambiar dos parámetros de sitio en un constructor fue una refactorización que ningún compilador señalaba y que podía intercambiar dos valores en cada punto donde alguien desestructuraba tu tipo. Kotlin 2.3.20 rompió con esa herencia introduciendo el desestructurado basado en nombres, que empareja variables con propiedades por identificador y no por posición. Es probablemente el cambio más importante que le ha pasado a las data class desde que existen.

La mecánica del desestructurado posicional

Una declaración desestructurada no es una característica de las data class: es una convención de operadores, como plus o invoke. El compilador reescribe la declaración en llamadas numeradas:

data class Usuario(val nombre: String, val email: String)

val (a, b) = usuario
// se traduce literalmente a
val a = usuario.component1()
val b = usuario.component2()

Lo que una data class aporta es la generación automática de esas funciones operator fun componentN, una por cada propiedad del constructor primario y en el orden en que aparecen. Cualquier tipo que declare esos operadores, aunque sea mediante funciones de extensión, se puede desestructurar; así es como funcionan Pair, Triple y las entradas de un mapa:

for ((clave, valor) in mapa) { /* usa Map.Entry.component1 y component2 */ }

lista.forEachIndexed { i, x -> /* dos parametros, no desestructurado */ }
mapa.mapValues { (_, valor) -> valor.trim() }  // un par desestructurado

El guion bajo salta un componente y, además, evita la llamada al operador correspondiente. Y hay una diferencia sintáctica que confunde a mucha gente: en una lambda, dos parámetros separados por coma son dos parámetros, mientras que los mismos nombres entre paréntesis son un único parámetro que se desestructura.

val f = { a: Int, b: Int -> a + b }        // dos parametros
val g = { (a, b): Pair<Int, Int> -> a + b } // un parametro desestructurado

Como las componentN son operadores ordinarios, puedes habilitar el desestructurado en tipos ajenos que no controlas, incluidos los de la biblioteca estándar de la plataforma, con simples funciones de extensión. Es un mecanismo abierto, y esa apertura es justamente lo que lo hace tan difícil de auditar:

operator fun java.time.LocalDate.component1(): Int = year
operator fun java.time.LocalDate.component2(): Int = monthValue
operator fun java.time.LocalDate.component3(): Int = dayOfMonth

val (anio, mes, dia) = java.time.LocalDate.now()

El orden es el contrato, y nadie lo vigila

Aquí está el defecto de diseño. Los nombres que escribes en la declaración desestructurada son locales y arbitrarios: el compilador no los compara con nada. Solo cuenta posiciones:

data class Usuario(val nombre: String, val email: String)

val usuario = Usuario("alicia", "alicia@ejemplo.test")
val (email, nombre) = usuario

println(email)   // alicia
println(nombre)  // alicia@ejemplo.test

El código compila sin un solo aviso y hace exactamente lo contrario de lo que se lee. Peor todavía es el escenario evolutivo: publicas un tipo con nombre y email en ese orden, alguien desestructura correctamente, y seis meses después alguien reordena el constructor por estética o al añadir un parámetro. Como ambas propiedades son String, el desestructurado del consumidor sigue compilando y ahora asigna los valores cruzados. No hay error de tipos, no hay aviso de deprecación, no hay nada. El fallo aparece a kilómetros del cambio, normalmente en un correo enviado a la dirección equivocada.

Kotlin 2.3.20: emparejar por nombre

La solución que introdujo Kotlin 2.3.20, todavía en estado experimental, invierte el criterio: las variables se corresponden con las propiedades por nombre, y la posición deja de significar nada. La forma explícita declara cada variable con su propio val y, si quieres, la liga a una propiedad concreta:

// Forma explicita: cada variable dice de que propiedad viene
(val correo = email, val alias = nombre) = usuario

println(alias)   // alicia
println(correo)  // alicia@ejemplo.test

Ahora el orden en que escribas los elementos es irrelevante, y si el nombre de la propiedad desaparece o cambia, el compilador falla en el punto exacto del uso en vez de asignar valores cruzados. La refactorización deja de ser una operación de fe.

Junto con esta forma llega una segunda novedad sintáctica: los corchetes pasan a ser el desestructurado posicional explícito, reservado para los tipos donde el orden sí es la semántica, como listas, colecciones ordenadas y tuplas sin nombre como Pair o Triple:

val punto = Pair(10, 20)
val [x, y] = punto   // aqui la posicion es el contrato, y esta bien que lo sea

flowchart TD
A[Declaracion desestructurada] --> B{Que significa la posicion}
B -->|Nada, hay nombres| C[Parentesis con nombres de propiedad]
B -->|Todo, es una tupla| D[Corchetes posicionales]
C --> E[El compilador falla si el nombre no existe]
D --> F[El compilador usa componentN por orden]
E --> G[Refactorizar el constructor es seguro]
F --> H[Reordenar cambia el significado en silencio]

La distinción es conceptualmente limpia: los paréntesis son para registros, donde cada campo tiene nombre y el orden es un accidente de escritura; los corchetes son para secuencias, donde el orden es la información. Que durante quince años ambas cosas compartieran sintaxis es exactamente la razón de que el problema existiera.

Migrar sin sustos: los tres modos del compilador

La característica se activa con la opción -Xname-based-destructuring, que admite tres modos pensados para recorrerse en orden y no de un salto.

kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xname-based-destructuring=name-mismatch")
    }
}

El modo only-syntax habilita la forma explícita con nombres y la forma posicional con corchetes, sin cambiar el comportamiento de nada de lo que ya tienes escrito: es aditivo y no puede romper nada. El modo name-mismatch es el interesante durante la transición, porque emite avisos allí donde un desestructurado posicional sobre una data class usa nombres de variable que no coinciden con los de las propiedades; es decir, te enseña la lista exacta de sitios donde el significado del código cambiaría, que resulta ser también la lista de sitios donde probablemente ya tenías un fallo latente. El modo complete da el paso final: la forma corta entre paréntesis pasa a emparejar por nombre, y el desestructurado posicional queda relegado a los corchetes.

El itinerario responsable es evidente. Activa name-mismatch, resuelve todos los avisos renombrando variables o adoptando la forma explícita, revisa que ningún desestructurado sobre Pair, Triple o colecciones se haya quedado con paréntesis, y solo entonces pasa a complete. Saltar directamente al último modo en una base de código grande es la manera más eficiente de convertir un problema latente en un incidente.

flowchart LR
A[Estado inicial sin la opcion] --> B[only-syntax]
B --> C[name-mismatch con avisos]
C --> D[Revisar cada aviso uno a uno]
D --> E[Reescribir con nombres o corchetes]
E --> F[complete]

Merece la pena insistir en que la característica es experimental y que eso tiene dos implicaciones prácticas. La primera es que la sintaxis y los detalles de los modos pueden afinarse en versiones posteriores, de modo que no conviene apoyar en ella la superficie pública de una librería que otros consuman antes de que se estabilice. La segunda, más optimista, es que el modo name-mismatch es útil aunque nunca llegues a activar complete: funciona como un analizador estático gratuito que te señala desestructurados sospechosos, y ese valor lo obtienes sin comprometerte con ningún cambio de comportamiento. Activarlo en integración continua y tratar sus avisos como deuda a revisar es probablemente la decisión de mejor relación entre coste y beneficio que puedes tomar hoy sobre este asunto.