Serialización: kotlinx frente a Moshi y el esquema que cambia

La serialización tiene una reputación inmerecida de trabajo aburrido y resuelto. Se elige una biblioteca, se anotan unas clases de datos y se pasa a lo interesante. Esa percepción sobrevive exactamente hasta el primer incidente en producción, que casi siempre tiene la misma forma: el servidor añadió un campo, o dejó de enviar uno, o cambió un valor de enumeración, y una fracción de los usuarios empezó a ver una pantalla vacía sin que nadie tocara una línea del cliente. El problema de fondo no es técnico sino temporal. Una clase de datos anotada es una afirmación sobre la forma de unos bytes que llegarán en el futuro, escrita por alguien que solo conoce la forma que tenían en el pasado, y compilada dentro de un binario que sobrevivirá años en dispositivos que quizá nunca se actualicen. Entender qué hace exactamente cada biblioteca cuando la realidad se aparta de esa afirmación es lo que separa una capa de datos que degrada con elegancia de una que se rompe entera por un campo de más.

Dos modelos de generación, no dos sintaxis

kotlinx.serialization funciona mediante un complemento del compilador de Kotlin que, al ver la anotación @Serializable, genera un serializador para esa clase durante la propia compilación. No hay reflexión en tiempo de ejecución, el descriptor del tipo se conoce estáticamente y el mecanismo funciona igual en todos los destinos que Kotlin sabe compilar, incluidos los que no tienen reflexión en absoluto. Esa es la razón profunda por la que es la opción natural en un proyecto multiplataforma y por la que se lleva bien con la reducción agresiva de código.

Moshi es una biblioteca de Java pensada para el mundo de la máquina virtual, con dos modos de operación. El modo de generación produce adaptadores mediante un procesador de anotaciones, con un rendimiento equivalente y sin reflexión en el camino caliente. El modo reflexivo interpreta la clase en tiempo de ejecución, lo que resulta cómodo y cuesta arranque, memoria y reglas de conservación al minimizar el binario. Su virtud histórica y todavía vigente es la calidad de su modelo de adaptadores: componer, envolver y sustituir la conversión de un tipo concreto es más natural que en casi cualquier alternativa.

La declaración de un mismo modelo en ambas bibliotecas es casi idéntica, y esa semejanza superficial es precisamente lo que hace que la discusión se desvíe hacia la sintaxis. Lo que cambia no es cómo se escribe sino cuándo y dónde se decide el esquema.

// kotlinx.serialization: el esquema se resuelve al compilar
@Serializable
data class UsuarioDto(
    val id: String,
    @SerialName("display_name") val nombre: String,
    val verificado: Boolean = false,
)

// Moshi con generacion: adaptador producido por el procesador
@JsonClass(generateAdapter = true)
data class UsuarioMoshi(
    val id: String,
    @Json(name = "display_name") val nombre: String,
    val verificado: Boolean = false,
)

La comparación honesta termina en un empate técnico para el caso corriente y en dos criterios de decisión claros. Si el modelo de datos se comparte entre plataformas o si el proyecto ya es de Kotlin en su totalidad, kotlinx.serialization es la respuesta por defecto. Si existe una inversión importante en adaptadores propios, en interoperabilidad con Java o en una jerarquía polimórfica compleja ya modelada, migrar por moda es gastar semanas para llegar al mismo sitio.

Ausente, nulo y por defecto son tres cosas

Aquí está la confusión que más incidentes produce, y se despeja enunciando la distinción con precisión. Un campo puede no aparecer en el documento recibido; puede aparecer con el valor nulo explícito; o puede no aparecer y ser rellenado con un valor por defecto declarado en el cliente. Son tres situaciones distintas con tres significados distintos, y el comportamiento por defecto de cada biblioteca las colapsa de maneras diferentes.

En kotlinx.serialization, un campo sin valor por defecto que no aparece en el documento provoca una excepción por campo ausente, incluso si su tipo es anulable. Esa severidad es deliberada y a menudo la correcta: si el contrato dice que ese dato existe, su ausencia es un fallo del contrato y no un valor vacío. Un campo con valor por defecto declarado, en cambio, simplemente lo toma. Y un nulo explícito sobre un tipo no anulable falla, salvo que se active la coerción de valores de entrada, que lo sustituye por el valor por defecto.

@Serializable
data class ProductoDto(
    val id: String,
    val nombre: String,
    val descripcion: String? = null,        // ausente o nulo, ambos valen
    val etiquetas: List<String> = emptyList(),  // ausente, lista vacia
    val descuento: Int = 0,                  // ausente o nulo con coercion
)

val analizador = Json {
    ignoreUnknownKeys = true
    coerceInputValues = true
    explicitNulls = false
}

Las tres opciones del analizador merecen entenderse una a una porque cada una compra algo distinto. Ignorar claves desconocidas es innegociable: sin ella, el día en que el servidor añada un campo que tu versión no conoce, la aplicación instalada dejará de analizar la respuesta entera. La coerción convierte nulos inesperados y valores de enumeración desconocidos en el valor por defecto en lugar de fallar. Y desactivar los nulos explícitos hace dos cosas: al escribir omite los campos nulos en lugar de emitirlos, y al leer permite que un campo anulable ausente valga nulo sin necesidad de declararle un valor por defecto.

Moshi en su modo generado se comporta de forma parecida pero no idéntica: un campo ausente toma el valor por defecto si lo hay y falla si no lo hay, y un nulo explícito sobre un tipo no anulable produce una excepción de datos que nombra el campo y su ruta dentro del documento. Esa calidad de mensaje es una de sus mejores propiedades prácticas cuando hay que diagnosticar un documento grande.

El esquema cambia, y tu binario no

La regla que gobierna toda esta sección es que el cliente instalado no se actualiza cuando el servidor sí. En cualquier momento existe una población de versiones antiguas en circulación, y el conjunto de decisiones de compatibilidad tiene que tomarse pensando en ellas y no en la versión que hoy tienes abierta en el editor.

flowchart TD
A[Llega un documento] --> B{La clave existe en el modelo}
B -->|No| C[Se ignora si asi esta configurado]
B -->|Si| D{Aparece el campo}
D -->|No| E{Hay valor por defecto}
E -->|Si| F[Toma el valor por defecto]
E -->|No| G[Fallo por campo ausente]
D -->|Si| H{El valor es nulo}
H -->|Si| I{El tipo admite nulo}
I -->|Si| J[Queda nulo]
I -->|No| K[Coercion al valor por defecto o fallo]
H -->|No| L[Se convierte al tipo declarado]
style F fill:#a6e3a1,color:#11111b
style G fill:#f38ba8,color:#11111b
style K fill:#f9e2af,color:#11111b

De ese diagrama salen cuatro reglas operativas. La primera es que todo campo añadido después de la versión inicial debe llegar con valor por defecto en el cliente, porque las versiones antiguas no lo conocen y las nuevas deben tolerar que un servidor todavía no desplegado no lo envíe. La segunda es que un campo nunca se elimina ni se renombra: se deja de usar y se sigue enviando, o se declara con un alias que acepta el nombre antiguo y el nuevo simultáneamente durante la transición.

La tercera regla afecta a las enumeraciones y es la fuente más frecuente de fallos silenciosos en aplicaciones maduras. Un valor nuevo en un catálogo del servidor rompe cualquier cliente que traduzca esa cadena a una enumeración cerrada. La defensa es una constante de reserva que absorba lo desconocido, mediante coerción hacia el valor por defecto en kotlinx.serialization o mediante un adaptador con repliegue en Moshi. La cuarta afecta a las jerarquías polimórficas: cuando el tipo se decide por un campo discriminador, hay que declarar qué ocurre con un discriminador que el cliente no reconoce, y la respuesta sana casi siempre es una variante desconocida que la interfaz pueda ignorar sin dejar de dibujar el resto de la lista.

@Serializable
sealed interface Bloque {
    @Serializable @SerialName("texto")
    data class Texto(val contenido: String) : Bloque

    @Serializable @SerialName("imagen")
    data class Imagen(val url: String, val alto: Int = 0) : Bloque

    // Absorbe cualquier discriminador futuro sin romper la pantalla.
    @Serializable @SerialName("desconocido")
    data object Desconocido : Bloque
}

El renombrado merece una precisión operativa, porque la segunda regla suele leerse como una prohibición absoluta y no lo es. Renombrar es posible si durante la transición el modelo acepta ambos nombres a la vez, con la anotación de nombres alternativos en kotlinx.serialization o con un adaptador que contemple los dos en Moshi. Lo que no es posible es hacer el cambio de golpe: hay que aceptar ambos, esperar a que la población de clientes antiguos sea despreciable —lo que se mide, no se supone— y solo entonces retirar el nombre viejo.

Conviene también resistir la tentación de resolver todo esto con una versión en la ruta del punto final. Versionar la API es una herramienta legítima para cambios que rompen el contrato de raíz, pero usarla como sustituto de la compatibilidad hacia atrás multiplica el trabajo del servidor por el número de versiones vivas y no elimina el problema: dentro de cada versión sigue habiendo evolución, y sigue haciendo falta que los campos nuevos lleguen con valor por defecto.

Hay una última decisión estructural que conviene tomar pronto porque es carísima de revertir: los tipos que se anotan para serializar no deben ser los tipos que usa el resto de la aplicación. Un modelo de transferencia refleja el capricho del servidor —campos anulables que en tu dominio nunca lo son, fechas como cadenas, códigos numéricos, nombres en otro idioma— y su forma cambia cuando el servidor cambia. Un modelo de dominio expresa lo que tu aplicación entiende, con tipos que hacen imposibles los estados inválidos. La función de mapeo entre ambos es donde se concentra la validación, y su existencia es lo que permite que un cambio remoto se detenga en la capa de datos en vez de propagarse hasta la pantalla.