Ecosystem

Lanzamos kotlinx.serialization 1.2: gestión de JSON a alta velocidad, compatibilidad con clases de valores, documentos totalmente renovados y mucho más

¡Ya está aquí kotlinx.serialization 1.2! La versión más reciente de nuestra biblioteca de serialización multiplataforma aporta numerosas mejoras. Estas son algunas de las más destacadas:

• La serialización en JSON es más rápida que nunca. La versión 1.2 es hasta el doble de rápida que las versiones anteriores al analizar JSON en objetos Kotlin de tipo seguro y convertir objetos Kotlin en sus representaciones de texto.
• Ahora se admiten las incorporaciones al sistema de tipo Kotlin 1.5. Las clases de valores y los números no firmados se pueden convertir a JSON y de vuelta como cualquier otra clase Kotlin.
• La nueva documentación API explica de forma sencilla todas las funcionalidades que kotlinx.serialization ofrece.

La versión 1.2 también incluye nueva compatibilidad con nombres alternativos para campos JSON, y ofrece un nuevo enfoque experimental que automáticamente genera esquemas Protobuf a partir de clases Kotlin, ¡una funcionalidad de la que estamos deseando recibir su feedback!

¡Veamos juntos los cambios e incorporaciones a esta nueva versión! Si ya está convencido, por supuesto puede pasar directamente a las instrucciones de actualización que encontrará a continuación.

¡Comience a utilizar kotlinx.serialization 1.2!

¡Suscríbase al canal de YouTube de Kotlin!

Codificación y decodificación JSON más rápida que nunca

La capacidad de codificar clases de Kotlin en cadenas de JSON y la posibilidad de convertir cadenas de JSON en clases de Kotlin son las funcionalidades más utilizadas de kotlinx.serialization, y trabajamos constantemente para mejorar su rendimiento.

La versión 1.2 renueva por completo la estructura interna de kotlinx.serialization, para lograr un rendimiento significativamente mejor en estas funciones esenciales. Hemos reescrito nuestro decodificador JSON (responsable de convertir texto en objetos de Kotlin), y hemos realizado optimizaciones significativas en nuestro codificador JSON (responsable de convertir los objetos Kotlin en texto).

Con solo actualizar a la última versión de nuestra biblioteca, puede lograr hasta el doble de la velocidad en tareas de codificación y decodificación habituales. (Como ve, algunas de nuestras referencias internas, que se vieron particularmente afectadas por estas nuevas optimizaciones, ¡incluso superan esa cifra!)

Con estos cambios, kotlinx.serialization logra (y en ocasiones supera) el mismo rendimiento que otras bibliotecas de JSON directamente sin configuración adicional. Incluso los fragmentos de código más simples se ven beneficiados por esta renovación:

@Serializable
data class User(val name: String, val yearOfBirth: Int)

fun main() {
// Faster encoding...
val data = User("Louis", 1901)
val string = Json.encodeToString(data)
println(string) // {"name":"Louis","yearOfBirth":1901}

// ...and faster decoding!
val obj = Json.decodeFromString(string)
println(obj) // User(name=Louis, yearOfBirth=1901)
}

El mejor modo de percibir estas mejoras es marcar referencias en su propia aplicación con la versión más reciente de su biblioteca. Si desea hacerse una idea de las cifras generales de rendimiento, puede echar un vistazo a nuestras referencias internas para la codificación y la decodificación, que comparan la última versión de kotlinx.serialization con la versión anterior.

(De)serialización de JSON estable para clases de valores y tipos de números no firmados

Kotlin 1.5.0 incorpora dos novedades geniales, clases de valores y tipos de enteros no firmados, para lo cual kotlinx.serialization 1.2 ahora ofrece una excelente asistencia a la codificación y decodificación JSON. Echemos un vistazo más de cerca.

Compatibilidad con clases de valores

Las clases de valores (anteriormente denominadas clases en línea) son un modo de ajustar otro tipo Kotlin (por ejemplo, un número) de un modo de tipo seguro sin introducir carga de tiempo de ejecución adicional. Esto le ayuda a crear programas más expresivos y seguros sin poner en entredicho el rendimiento.

La serialización de JSON integrada en kotlinx.serialization ahora funciona con clases de valores. Al igual que en las demás clases de Kotlin, solo tenemos que anotar una clase de valor con @Serializable.

@Serializable
value class Color(val rgb: Int)

Las clases de valores se almacenan (y serializan) directamente como su tipo subyacente. Podemos verlo añadiendo un campo con un tipo de clase de valor a una clase de datos serializable, e inspeccionando su resultado:

@Serializable
data class NamedColor(val color: Color, val name: String)

fun main() {
println(Json.encodeToString(NamedColor(Color(0), "black")))
}

// {"color": 0, "name": "black"}

En el ejemplo anterior, NamedColor trata la clase de valor Color como la primitiva subyacente (una Int). Esto significa que disfrutará de la máxima seguridad de tipo dentro de su código Kotlin, y continuará gozando de una representación serializada concisa de estos tipos, sin delimitación ni anidado necesarios.

Todavía estamos puliendo el diseño de los serializadores personalizados, escritos a mano, para clases de valores, y de momento continúan siendo experimentales. Encontrará más información a este respecto en los docs de GitHub.

Compatibilidad con enteros no firmados

Los enteros no firmados son una incorporación a la biblioteca estándar de Kotlin que ofrece tipos y operaciones para números no negativos. Con el lanzamiento de Kotlin 1.5.0 están disponibles los siguientes tipos de números no firmados:

• UByte, con valores de 0 a 255
• UShort, con valores de 0 a 65535
• UInt, con valores de 0 a 2^32 – 1
• ULong, con valores de 0 a 2^64 – 1

El codificador y decodificador de JSON en kotlinx.serialization ahora es compatible con estos tipos directamente sin configuración adicional. Al igual que otros tipos numéricos, los valores enteros no firmados se serializarán en su representación numérica sencilla (la misma representación que ve al invocar .toString), sin truncado, ajuste de texto ni conversión a tipos firmados.

@Serializable
class Counter(val counted: UByte, val description: String)

@Serializable
class BigCounter(val counted: ULong)

val counted = 239.toUByte()
println(Json.encodeToString(Counter(counted, "tries")))
// {"counted":239,"description":"tries"}

println(Json.encodeToString(BigCounter(ULong.MAX_VALUE)))
// {"counted":18446744073709551615}

Tenga en cuenta que la compatibilidad con clases de valores y enteros no firmados está actualmente disponible para JSON. En una futura versión, también incorporaremos integraciones directas para CBOR y Protobuf, ¡esté atento!

Si desea mantenerse al día de futuros lanzamientos de kotlinx.serialization y del lenguaje de programación de Kotlin, suscríbase al boletín de actualizaciones de producto de Kotlin a través del formulario que encontrará junto a este artículo.

Para obtener información detallada acerca del uso de clases de valores y tipos no firmados con kotlinx.serialization, eche un vistazo a la documentación de GitHub.

Compatibilidad con nombres alternativos para campos JSON

A veces necesita analizar campos JSON que tienen distintos nombres pero el mismo significado, por ejemplo, para mantener la compatibilidad retroactiva. Con la nueva anotación @JsonNames, ahora puede dar nombres alternativos a los campos JSON, lo cual se utilizará durante el proceso de decodificación.

Para ilustrarlo, veamos un ejemplo. Imaginemos que, dependiendo de su versión, un servidor nos da una de las dos respuestas siguientes:

{"name":"kotlinx.serialization"}
/* ...or: */
{"title":"kotlinx.serialization"}

name y title tienen el mismo significado, y queremos mapearlas al mismo campo en nuestra clase Kotlin. Con la nueva anotación @JsonNames, podemos especificar title como clave alternativa para la clave name:

@Serializable
data class Project(@JsonNames("title") val name: String)

Fíjese en la diferencia con la anotación @SerialName, que le permite renombrar campos tanto para codificar como para decodificar, pero no le permite especificar alternativas.

Esperamos que esta funcionalidad le facilite el trabajo con servicios que devuelven campos con nombres distintos que representan los mismos valores, sobreviven a migraciones de esquema y ofrecen estupendas actualizaciones para sus aplicaciones.

Nueva documentación API

Para que su experiencia con el aprendizaje kotlinx.serialization sea lo más cómoda y divertida posible, tratamos de ofrecerle gran cantidad de materiales de referencia. Uno de ellos es la Kotlin Serialization Guide en GitHub, que ofrece una visión general de las funcionalidades que aporta la biblioteca e incluye ejemplos autocontenidos para que comprenda de forma intuitiva cada funcionalidad.

Otro es la documentación API de kotlinx.serialization, que hemos renovado por completo. Basándose en una nueva versión de Dokka, el motor de documentación de Kotlin, la nueva documentación de la API incluye un nuevo diseño moderno y receptivo, así como símbolos por los que resulta sencillo navegar.

¡Explore la nueva documentación API de kotlinx.serialization!

Protobuf: generación de esquemas experimental desde clases Kotlin

Protocol Buffers (Protobuf) es un formato de serialización binario para datos estructurados creado por Google. Como formato binario, es más eficiente en cuanto a espacio que JSON o XML, y aún así ofrece una estructura independiente del lenguaje que puede utilizar para la comunicación entre aplicaciones.

Con kotlinx.serialization, puede utilizar serialización Protobuf multiplataforma (usando semántica proto2) con estabilidad experimental. Como en los demás formatos, anote su clase como @Serializable y utilice los métodos incorporados encode / decode:

@Serializable
data class Project(val name: String, val language: String)

fun main() {
val data = Project("kotlinx.serialization", "Kotlin")
val bytes = ProtoBuf.encodeToByteArray(data)
println(bytes.toAsciiHexString())
val obj = ProtoBuf.decodeFromByteArray(bytes)
println(obj)
}

Con sus clases de Kotlin como fuente de referencia (junto con cualquier personalización que desee aplicar), kotlinx.serialization es capaz de inferir el esquema binario de los datos, haciendo que la comunicación Protobuf entre múltiples aplicaciones Kotlin resulte concisa y práctica.

kotlinx.serialization 1.2 ahora incluye un generador de esquemas para Protocol Buffers experimental. Le permite generar archivos .proto desde sus clases de datos Kotlin, lo que a su vez puede utilizarse para generar representaciones de su esquema de comunicación en otros lenguajes, incluidos Python, C++ y TypeScript.

Para obtener instrucciones sobre cómo comenzar con el nuevo generador de esquemas, compruebe las instrucciones correspondientes en la documentación.

Cuando se haya generado el archivo .proto, puede almacenarlo en su repositorio y utilizarlo para generar representaciones de sus clases Kotlin en otros lenguajes. Esperamos que esto le facilite el uso de la integración Protobuf de kotlinx.serialization en aplicaciones multilenguaje sin tener que renunciar a la comodidad de gestionar sus esquemas directamente en el código fuente Kotlin.

Como esta es la primera iteración del generador de esquemas Protobuf, confiamos en gran medida en su feedback. Por favor, pruébelo y cuéntenos sus casos de uso, cómo gestiona sus modelos y archivos .proto, cualquier problema que se encuentre y las funcionalidades que le gustaría que incorporásemos, utilizando el sistema de seguimiento de incidencias de GitHub.

Al trabajar con el generador de esquemas, por favor, no olvide sus limitaciones. Como norma general, si una clase de Kotlin se puede serializar con la implementación Protobuf incluida con kotlinx.serialization, el generador de esquemas ofrecerá compatibilidad con ella. Esto también significa que son aplicables las mismas restricciones. Estos son algunos puntos que debe tener en cuenta:

• Las clases y nombres de propiedades de Kotlin deben adaptarse a la especificación de Protobuf, y no contienen caracteres ilegales.
• La nulidad de Kotlin no se refleja en el esquema (porque proto2 no dispone de semántica para ello). Los campos opcionales que ofrecen los buffers de protocolo se utilizan basándose en si sus propiedades de Kotlin definen valores predeterminados.
• Los valores predeterminados de Kotlin no se incluyen en el esquema (lo que significa que tendrá que garantizar por su cuenta la coherencia de los valores predeterminados en diferentes implementaciones de lenguaje.)

¡Comience a utilizar kotlinx.serialization 1.2!

¡Con esto acaba nuestro resumen! Si está listo para disfrutar de una codificación y decodificación más rápida en JSON, compatibilidad con incorporaciones al sistema de tipo Kotlin 1.5, generación de esquemas Protobuf y más, ¡es el momento de actualizar!

Si ya está utilizando kotlinx.serialization, actualizar a la versión 1.2 es muy rápido (y si no ha probado kotlinx.serialization ¡es un buen momento para comenzar!). En primer lugar, actualice el bloque plugins en su archivo build.gradle.kts:

plugins {
kotlin("jvm") version "1.5.0" // or kotlin("multiplatform") or any other kotlin plugin
kotlin("plugin.serialization") version "1.5.0"
}

A continuación, actualice su bloque dependencies con la biblioteca runtime, incluyendo los formatos que desea utilizar en su aplicación:

dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.1")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-protobuf:1.2.1")
// . . .
}

Ver y leer más

• Vídeo de kotlinx.serialization 1.2
• Biblioteca en GitHub
• Guía de kotlinx.serialization
• Documentación API
• Artículo del blog del lanzamiento de Kotlin 1.5.0

Si tiene algún problema

• Informe acerca de incidencias en nuestro sistema de seguimiento de incidencias de GitHub.
• Busque ayuda en el canal #serialization de Kotlin Slack (obtenga una invitación).

¡Suscríbase al canal de YouTube de Kotlin! ¡Que disfrute de la (de)serialización!