Ecosystem

Publication de kotlinx.serialization 1.2 : traitement JSON deux fois plus rapide, prise en charge des classes value, documentation remaniée, et plus encore

kotlinx.serialization 1.2 est là ! La dernière version de notre bibliothèque de sérialisation multiplateforme apporte un certain nombre d’améliorations, notamment :

• Une augmentation significative de la vitesse de la sérialisation JSON. Avec la version 1.2 , l’analyse de JSON en objets Kotlin de type sécurisé et la conversion des objets Kotlin en représentations textuelles sont jusqu’à deux fois plus rapides qu’avec la version précédente.
• Les ajouts au système de types de Kotlin 1.5 sont désormais pris en charge. Les classes value et les nombres non signés peuvent être convertis en JSON et inversement, comme toute autre classe Kotlin.
• La nouvelle documentation de l’API facilite la découverte des différentes fonctionnalités de kotlinx.serialization.

La version 1.2 apporte aussi une nouvelle prise en charge des noms alternatifs pour les champs JSON et une nouvelle approche expérimentale qui génère automatiquement des schémas Protobuf à partir de classes Kotlin, une fonctionnalité à propos de laquelle nous avons hâte de recevoir vos commentaires !

 

Examinons ensemble les changements et les ajouts que comporte cette nouvelle version ! Si vous êtes déjà convaincu·e, vous pouvez passer directement aux instructions de mise à niveau incluses à la fin de cet article !

Commencez à utiliser kotlinx.serialization 1.2 !

Abonnez-vous à la chaîne YouTube de Kotlin !

Encodage et décodage JSON bien plus rapides

La possibilité d’encoder les classes Kotlin en chaînes JSON et celle de de transformer les chaînes JSON en classes Kotlin sont les fonctionnalités les plus utilisées de kotlinx.serialization, et nous travaillons constamment à les rendre plus performantes.

La version 1.2 remanie complètement la structure interne de kotlinx.serialization, ce qui permet d’obtenir de bien meilleures performances pour ces fonctionnalités essentielles. Nous avons réécrit notre décodeur JSON (pour la conversion de texte en objets Kotlin) et apporté d’importantes optimisations à notre encodeur JSON (pour la conversion des objets Kotlin en texte).

En utilisant la dernière version de notre bibliothèque, vous pouvez bénéficier d’une vitesse jusqu’à deux fois supérieure pour les tâches de codage et de décodage classiques. (Comme vous pouvez le voir certains des tests que nous avons réalisés en interne montrent même une vitesse supérieure !)

Avec ces changements, kotlinx.serialization atteint le même niveau de performance (voire un niveau supérieur à certains égards) que d’autres autres bibliothèques JSON prêtes à l’emploi. Même les extraits de code les plus simples bénéficient de ces améliorations :

<br />@Serializable<br />data class User(val name: String, val yearOfBirth: Int)</p>
<p>fun main() {<br />// Faster encoding...<br />val data = User("Louis", 1901)<br />val string = Json.encodeToString(data)<br />println(string) // {"name":"Louis","yearOfBirth":1901}</p>
<p>// ...and faster decoding!<br />val obj = Json.decodeFromString(string)<br />println(obj) // User(name=Louis, yearOfBirth=1901)<br />}<br />

La meilleure façon de se faire une idée de ces améliorations est de tester votre propre application avec la dernière version de notre bibliothèque. Pour une estimation des performances, consultez nos benchmarks internes pour l’encodage et le décodage qui comparent la dernière version de kotlinx.serialization à la précédente version .

Sérialisation et désérialisation JSON stable pour les classes value et les types de nombres non signés

La version 1.5.0 de Kotlin récemment publiée a apporté les classes value et les types d’entiers non signés, pour lesquels kotlinx.serialization 1.2 offre maintenant une prise en charge de l’encodage et du décodage JSON de premier ordre. Voyons cela de plus près.

Prise en charge des classes value

Les classes value (auparavant appelées classes inline) sont un moyen d’encapsuler un autre type Kotlin (par exemple, un nombre) de manière sécurisée, sans risque de surcharge lors de l’exécution. Cela permet de rendre vos programmes plus expressifs et sûrs, sans affecter les performances.

La sérialisation JSON intégrée de kotlinx.serialization fonctionne maintenant pour les classes value. Comme pour les autres classes Kotlin, il suffit d’annoter une classe value avec @Serializable.

<br />@Serializable<br />value class Color(val rgb: Int)<br />

Les value class sont stockées (et sérialisées) directement comme leur type sous-jacent. Nous pouvons le voir en ajoutant un champ avec un type value class à une data class sérialisable et en examinant sa sortie :

<br />@Serializable<br />data class NamedColor(val color: Color, val name: String)</p>
<p>fun main() {<br />println(Json.encodeToString(NamedColor(Color(0), "black")))<br />}</p>
<p>// {"color": 0, "name": "black"}<br />

Dans l’exemple ci-dessus, NamedColor traite la value class Color comme la primitive sous-jacente (un Int). Cela signifie que vous bénéficiez d’une sécurité de type maximale dans votre code Kotlin, tout en profitant d’une représentation sérialisée concise de ces types, sans encapsulation ou imbrication inutile.

Nous sommes toujours en train d’affiner le design des sérialiseurs personnalisés écrits à la main pour les classes value class et ils sont encore expérimentaux pour le moment. Vous pouvez en apprendre davantage sur ce sujet dans les docs sur GitHub.

Prise en charge des entiers non signés

Les entiers non signés sont un ajout à la bibliothèque standard de Kotlin qui fournissent des types et des opérations pour les nombres non négatifs. Avec la publication de Kotlin 1.5.0, les types de nombres non signés suivants sont disponibles :

• UByte, avec des valeurs de 0 à 255
• UShort, avec des valeurs de 0 à 65535
• UInt, avec des valeurs de 0 à 2^32 – 1
• ULong, avec des valeurs de 0 à 2^64 – 1

L’encodeur et le décodeur JSON dans kotlinx.serialization prennent maintenant directement en charge ces types. Tout comme pour les autres types de nombres, les valeurs entières non signées seront sérialisées dans leur représentation numérique standard (la même représentation que vous voyez en invoquant .toString), sans troncature, encapsulation ou conversion en types signés.

<br />@Serializable<br />class Counter(val counted: UByte, val description: String)</p>
<p>@Serializable<br />class BigCounter(val counted: ULong)</p>
<p>val counted = 239.toUByte()<br />println(Json.encodeToString(Counter(counted, "tries")))<br />// {"counted":239,"description":"tries"}</p>
<p>println(Json.encodeToString(BigCounter(ULong.MAX_VALUE)))<br />// {"counted":18446744073709551615}<br />

Veuillez noter que la prise en charge des classes value et des entiers non signés est actuellement disponible pour JSON. Dans une prochaine version, nous fournirons également des intégrations directes pour CBOR et Protobuf !

Si vous souhaitez être informé·e des futures versions de kotlinx.serialization et du langage de programmation Kotlin, inscrivez-vous à la newsletter dédiée aux mises à jour des produits Kotlin via le formulaire figurant à côté de cet article !

Pour plus d’informations sur l’utilisation des classes value et des types non signés avec kotlinx.serialization, consultez la documentation sur GitHub.

Prise en charge des noms alternatifs pour les champs JSON

Vous avez parfois besoin d’analyser des champs JSON portant des noms différents mais ayant la même signification, par exemple pour maintenir une compatibilité rétroactive. Avec la nouvelle annotation @JsonNames, vous pouvez désormais donner aux champs JSON des noms alternatifs, qui seront utilisés lors du processus de décodage.

Pour illustrer cela, prenons un exemple. Supposons qu’en fonction de sa version, un serveur nous donne l’une des deux réponses suivantes :

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

name et title ont tous deux la même signification et nous voulons les mapper sur le même champ dans notre classe Kotlin. Avec la nouvelle annotation @JsonNames, nous pouvons spécifier title comme clé alternative pour la clé name :

<br />@Serializable<br />data class Project(@JsonNames("title") val name: String)<br />

Vous remarquerez la différence avec l’annotation @SerialName, qui vous permet de renommer les champs pour l’encodage et le décodage, mais ne vous permet pas de spécifier des alternatives.

Nous espérons que cette fonctionnalité vous permettra de travailler plus facilement avec des services qui renvoient des champs nommés différemment représentant les mêmes valeurs, de survivre aux migrations de schémas et d’assurer des mises à jour harmonieuses de vos applications !

Nouvelle documentation de l’API

Pour rendre votre apprentissage de kotlinx.serialization aussi simple et agréable que possible, nous proposons plusieurs documents de référence. L’un d’eux est le Guide Kotlin Serialization sur GitHub, qui présente les fonctionnalités de la bibliothèque et inclut des exemples complets pour vous aider à bien comprendre chaque fonctionnalité.

Par ailleurs, nous avons totalement remanié la documentation de l’API kotlinx.serialization. Basée sur une nouvelle version de Dokka, le moteur de documentation de Kotlin, la documentation de l’API dispose d’un nouveau design adaptatif et moderne, ainsi que de symboles faciles à parcourir.

Explorez la nouvelle documentation d’API kotlinx.serialization !

Protobuf : génération de schémas expérimentale à partir de classes Kotlin

Protocol Buffers (Protobuf) est un format de sérialisation binaire pour les données structurées créé par Google. En tant que format binaire, il requiert moins d’espace que JSON ou XML, tout en fournissant une structure indépendante du langage que vous pouvez utiliser pour la communication entre applications.

Avec kotlinx.serialization, vous pouvez utiliser la sérialisation multiplateforme Protobuf (en utilisant la sémantique Proto2) avec une stabilité expérimentale. Comme avec les autres formats, annotez votre classe comme @Serializable et utilisez les méthodes encode / decode intégrées :

<br />@Serializable<br />data class Project(val name: String, val language: String)</p>
<p>fun main() {<br />val data = Project("kotlinx.serialization", "Kotlin")<br />val bytes = ProtoBuf.encodeToByteArray(data)<br />println(bytes.toAsciiHexString())<br />val obj = ProtoBuf.decodeFromByteArray(bytes)<br />println(obj)<br />}<br />

Avec vos classes Kotlin comme “source of truth” (source de données unique et fiable), combinée à la personnalisation que vous pourriez vouloir appliquer, kotlinx.serialization est capable de déduire le schéma binaire des données, rendant ainsi la communication Protobuf entre plusieurs applications Kotlin concise et pratique.

kotlinx.serialization 1.2 comprend maintenant aussi un générateur de schémas expérimental pour Protocol Buffers. Il vous permet de générer des fichiers .proto à partir de vos classes de données Kotlin, qui peuvent à leur tour être utilisées pour générer des représentations de vos schémas de communication dans d’autres langages, notamment Python, C++ et TypeScript.

Pour savoir comment utiliser le nouveau générateur de schémas, consultez les instructions correspondantes dans la documentation.

Une fois le fichier .proto généré, vous pouvez le stocker dans votre référentiel et l’utiliser pour générer des représentations de vos classes Kotlin dans d’autres langages. Nous espérons que cela vous permettra d’utiliser plus facilement l’intégration Protobuf de kotlinx.serialization dans des applications multi-langages, sans avoir à renoncer à la commodité de gérer vos schémas directement dans le code source Kotlin.

Il s’agit de la première itération du générateur de schémas Protobuf, nous comptons donc beaucoup sur vos retours. Essayez-le et parlez-nous de vos cas d’utilisation, de la façon dont vous gérez vos modèles et vos fichiers .proto, des problèmes que vous rencontrez et des fonctionnalités dont vous voudriez disposer, en utilisant l’outil de suivi de GitHub.

Gardez à l’esprit que le générateur de schémas comprend certaines limites. En règle générale, si une classe Kotlin peut être sérialisée avec l’implémentation protobuf incluse dans kotlinx.serialization, alors le générateur de schémas la prendra en charge. Cela signifie également que les mêmes restrictions s’appliquent. Voici quelques points à surveiller :

• Les classes et noms de propriétés de Kotlin doivent se conformer à la spécification de protobuf et ne pas contenir de caractères non autorisés.
• La nullabilité de Kotlin n’est pas reflétée dans le schéma (parce que proto2 n’a pas de sémantique pour cela). Les champs optionnels tels que fournis par protocol buffers sont utilisés si vos propriétés Kotlin définissent des valeurs par défaut.
• Les valeurs par défaut de Kotlin ne sont pas incluses dans le schéma. (ce qui signifie que vous devrez assurer vous-même la cohérence des valeurs par défaut dans les différentes implémentations du langage)

Commencez à utiliser kotlinx.serialization 1.2 !

Voilà qui conclut notre aperçu général. Si nous vous avons donné envie de profiter de la rapidité de l’encodage et du décodage JSON, de la prise en charge des ajouts au système de types de Kotlin 1.5 et de la génération de schémas Protobuf, effectuez la mise à jour !

Si vous utilisez déjà kotlinx.serialization, la mise à niveau vers la version 1.2 est très rapide (et si vous n’avez pas encore essayé kotlinx.serialization, il est temps de vous lancer !). Tout d’abord, mettez à jour le bloc plugins dans votre fichier build.gradle.kts :

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

Ensuite, mettez à jour votre bloc dependencies avec la bibliothèque d’exécution, y compris les formats que vous voulez utiliser dans votre application :

<br />dependencies {<br />implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.0")<br />implementation("org.jetbrains.kotlinx:kotlinx-serialization-protobuf:1.2.0")<br />// . . .<br />}<br />

Plus de vidéos et d’articles

• Vidéo kotlinx.serialization 1.2
• Bibliothèque sur GitHub
• Guide kotlinx.serialization
• Documentation de l’API
• Article sur la publication de Kotlin 1.5.0

Si vous rencontrez des problèmes

• Signalez-les sur l’outil de suivi GitHub.
• Demandez de l’aide dans le canal Slack #serialization de Kotlin (obtenir une invitation).

Abonnez-vous à la chaîne YouTube de Kotlin !

Bonne (dé)sérialisation !

Auteur de l’article original en anglais : Sebastian Aigner