Ecosystem

kotlinx.serialization 1.2 veröffentlicht: schnelle JSON-Verarbeitung, Unterstützung von Werteklassen, überarbeitete Dokumentation und mehr

kotlinx.serialization 1.2 ist da! Die neueste Version unserer Multiplattform-Serialisierungsbibliothek enthält eine Reihe von Verbesserungen. Hier sind einige Highlights:

• Die JSON-Serialisierung erfolgt schneller als je zuvor. Beim Parsen von JSON in typsichere Kotlin-Objekte und bei der Konvertierung von Kotlin-Objekten in Textform ist Version 1.2 teilweise doppelt so schnell wie frühere Versionen.
• Mit Kotlin 1.5 eingeführte Typsystem-Ergänzungen werden jetzt unterstützt. Werteklassen und vorzeichenlose Zahlen können wie jede andere Kotlin-Klasse in JSON und zurück konvertiert werden.
• Dank der neuen API-Dokumentation sind alle Funktionen von kotlinx.serialization leicht zu finden und zu erkunden.

Neu in Version 1.2 ist auch die Unterstützung für alternative JSON-Feldnamen sowie ein experimenteller Ansatz zur automatischen Generierung von Protobuf-Schemas aus Kotlin-Klassen – eine Funktion, zu der wir gerne Feedback von Ihnen hätten!

Im Folgenden wollen wir einzeln auf die Änderungen und Ergänzungen in dieser neuen Version eingehen. Wenn wir Sie bereits überzeugt haben, können Sie natürlich über den nachstehenden Link auch direkt zur Upgrade-Anleitung gehen!

Mit kotlinx.serialization 1.2 loslegen

Abonnieren Sie Kotlin auf YouTube!

JSON-Codierung und -Decodierung schneller denn je

Das Konvertieren von Kotlin-Klassen in JSON-Zeichenfolgen und umgekehrt gehört zu den meistverwendeten Funktionen von kotlinx.serialization, und wir arbeiten ständig daran, die Performance in diesem Bereich zu verbessern.

In Version 1.2 wurde die interne Struktur von kotlinx.serialization komplett überarbeitet. Ein Ergebnis ist die deutlich verbesserte Performance in diesem Kernbereich. Wir haben unseren JSON-Decoder (zur Umwandlung von Text in Kotlin-Objekte) neu geschrieben und unseren JSON-Encoder (zur Umwandlung von Kotlin-Objekten in Text) umfassend optimiert.

Durch ein einfaches Upgrade auf die neueste Version unserer Bibliothek können Sie eine bis zu zweifache Beschleunigung von typischen Kodierungs- und Dekodierungsaufgaben erzielen. (Wie Sie sehen, wurden in einigen unserer internen Benchmarks, die von diesen neuen Optimierungen besonders stark profitieren, diese Werte sogar noch übertroffen!)

Mit diesen Änderungen erreicht kotlinx.serialization bereits im Lieferzustand das Leistungsniveau anderer JSON-Bibliotheken (und übertrifft diese in bestimmten Bereichen sogar). Selbst die einfachsten Codeschnipsel profitieren von dieser Überarbeitung:

@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)
}

Der beste Weg, um ein Gefühl für diese Verbesserungen zu bekommen, dürfte das Benchmarking Ihrer eigenen Anwendung mit der neuesten Version unserer Bibliothek sein. Einen groben Anhaltspunkt für die Leistung bieten unsere internen Benchmarks für Codierung und Dekodierung, die die neueste Version von kotlinx.serialization mit der Vorgängerversion vergleichen.

Stabile JSON-Serialisierung/Deserialisierung für Werteklassen und vorzeichenlose Zahlentypen

Kotlin 1.5.0 führt zwei aufregende Neuerungen ein: Werteklassen und vorzeichenlose Ganzzahltypen. kotlinx.serialization 1.2 bietet jetzt für beide erstklassige Unterstützung bei der JSON-Encodierung und -Decodierung. Schauen wir uns das einmal näher an.

Unterstützung für Werteklassen

Werteklassen (früher Inline-Klassen genannt) bieten eine Möglichkeit, einen anderen Kotlin-Typ (z. B. eine Zahl) ohne zusätzlichen Laufzeitaufwand typsicher zu verpacken. Dadurch können Sie Ihren Programmcode ohne Leistungseinbußen ausdrucksvoller und sicherer gestalten.

Die integrierte JSON-Serialisierung von kotlinx.serialization unterstützt jetzt Werteklassen. Wie bei anderen Kotlin-Klassen müssen wir dazu die Werteklasse nur mit der Annotation @Serializable versehen.

@Serializable
value class Color(val rgb: Int)

Werteklassen werden direkt als der zugrunde liegende Typ gespeichert (und serialisiert). Wir können dies erkennen, indem wir eine Werteklasse als Feld zu einer serialisierbaren Datenklasse hinzufügen und die entsprechende Ausgabe untersuchen:

@Serializable
value class Color(val rgb: Int)

Value classes are stored (and serialized) directly as their underlying type. We can see this by adding a field with a value class type to a serializable data class, and inspecting its output:

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

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

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

Im obigen Beispiel behandelt NamedColor die Werteklasse Color als den zugrunde liegenden primitiven Typ (Int). Dies bedeutet, dass Sie in Ihrem Kotlin-Code auf maximale Typsicherheit setzen können und dennoch von einer kompakten Serialisierung dieser Typen profitieren, ohne unnötiges Boxing oder Verschachteln.

Wir arbeiten noch an der Optimierung des Designs für handgeschriebene, benutzerdefinierte Serialisierer für Werteklassen, und daher verbleiben sie vorerst im experimentellen Stadium. Weitere Informationen zu diesem Thema finden Sie in der Dokumentation auf GitHub.

Unterstützung für vorzeichenlose Ganzzahlen

Vorzeichenlose Ganzzahlen sind eine Ergänzung für die Kotlin-Standardbibliothek, die jetzt auch für nicht negative Zahlen Typen und Operationen bereitstellt. Ab Kotlin 1.5.0 stehen die folgenden vorzeichenlosen Zahlentypen zur Verfügung:

• UByte mit Werten von 0 bis 255
• UShort mit Werten von 0 bis 65535
• UInt mit Werten von 0 bis 2^32 – 1
• ULong mit Werten von 0 bis 2^64 – 1

Der JSON-Encoder und -Decoder in kotlinx.serialization bietet jetzt integrierte Unterstützung für diese Typen. Wie die anderen Zahlentypen werden auch vorzeichenlose Ganzzahlen in ihrer einfachen Zahlendarstellung serialisiert (dieselbe Darstellung, die Sie beim Aufruf von .toString sehen) – ohne Kürzung, Wrapping oder Konvertierung in einen vorzeichenbehafteten Typ.

@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}

Bitte beachten Sie, dass die Unterstützung für Werteklassen und vorzeichenlose Ganzzahlen derzeit nur für JSON verfügbar ist. In einer künftigen Version werden auch direkte Integrationen für CBOR und Protobuf bereitgestellt – wir werden Sie informieren!

Um über künftige Versionen von kotlinx.serialization und die Programmiersprache Kotlin auf dem Laufenden zu bleiben, abonnieren Sie unseren Newsletter für Kotlin-Produktupdates über das Formular neben diesem Blogartikel.

Weitere Informationen zur Verwendung von Werteklassen und vorzeichenlosen Typen mit kotlinx.serialization finden Sie in der Dokumentation auf GitHub.

Unterstützung für alternative JSON-Feldnamen

Manchmal müssen wir JSON-Felder einlesen, die trotz unterschiedlicher Namen denselben Zweck haben – zum Beispiel aus Gründen der Abwärtskompatibilität. Mit der neuen Annotation @JsonNames können Sie JSON-Feldern jetzt alternative Namen zuweisen, die bei der Dekodierung verwendet werden.

Schauen wir uns das an einem Beispiel an. Nehmen wir an, dass uns ein Server je nach Version eine der beiden folgenden Antworten gibt:

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

Sowohl name als auch title haben dieselbe Bedeutung, und wir möchten beide in demselben Feld unserer Kotlin-Klasse speichern. Mit der neuen @JsonNames-Annotation können wir title als alternativen Schlüssel für name angeben:

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

Beachten Sie den Unterschied zur Annotation @SerialName, die es Ihnen ermöglicht, Felder umzubenennen – sowohl für die Encodierung als auch für die Decodierung –, jedoch nicht die Möglichkeit bietet, Alternativen anzugeben.

Wir hoffen, dass Ihnen dieses Feature in verschiedenen Szenarien das Leben erleichtern wird: bei der Arbeit mit Services, die unterschiedlich benannte Felder mit denselben Werten zurückgeben, bei der pannenfreien Durchführung von Schemamigrationen und bei der Bereitstellung von reibungslosen Upgrades für Ihre Anwendungen!

Neue API-Dokumentation

Um Ihnen das Einarbeiten in kotlinx.serialization so komfortabel und kurzweilig wie möglich zu machen, stellen wir Ihnen eine Reihe von Referenzmaterialien zur Verfügung. Dazu gehört der Kotlin-Serialisierungsleitfaden auf GitHub. Dieser bietet einen Überblick über die Funktionalität sowie jeweils eigenständige, intuitive Beispiele für die einzelnen Funktionen.

Auch die Dokumentation der kotlinx.serialization-API haben wir komplett überarbeitet. Basierend auf einer neuen Version der Kotlin-Dokumentationsengine Dokka verfügt die neue API-Dokumentation über ein neues, ansprechendes und modernes Design sowie Symbole, die die Navigation vereinfachen.

Entdecken Sie die neue Dokumentation der kotlinx.serialization-API!

Protobuf: experimentelle Schemagenerierung aus Kotlin-Klassen

Protocol Buffers (Protobuf) ist ein von Google konzipiertes binäres Serialisierungsformat für strukturierte Daten. Als Binärformat ist es platzsparender als JSON oder XML und bietet dennoch eine sprachunabhängige Struktur, die sich für die Kommunikation über Anwendungsgrenzen hinweg eignet.

kotlinx.serialization bietet Ihnen jetzt eine plattformübergreifende Protobuf-Serialisierung (mit proto2-Semantik) in einem experimentellen Stadium. Wie bei den anderen Formaten versehen Sie Ihre Klasse mit der Annotation @Serializable und verwenden die integrierten Methoden encode und 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)
}

Mit Ihren Kotlin-Klassen als source of truth (inklusive eventueller Anpassungen, die Sie vielleicht benötigen), kann kotlinx.serialization das binäre Schema der Daten ableiten. Dadurch kann Protobuf für die kompakte und komfortable Kommunikation zwischen mehreren Kotlin-Anwendungen verwendet werden.

kotlinx.serialization 1.2 enthält jetzt auch einen experimentellen Schemagenerator für Protocol Buffers. Dieser generiert aus Ihren Kotlin-Datenklassen .proto-Dateien, die Sie verwenden können, um Ihre Kommunikationsschemas in anderen Sprachen – einschließlich Python, C++ und TypeScript – darzustellen.

Anweisungen zur Verwendung des neuen Schemagenerators finden Sie im entsprechenden Bereich der Dokumentation.

Sobald die .proto-Datei generiert wurde, können Sie sie in Ihrem Repository speichern und zum Generieren von Darstellungen Ihrer Kotlin-Klassen in anderen Sprachen verwenden. Wir hoffen, dass Ihnen dies die Möglichkeit bietet, die Protobuf-Integration von kotlinx.serialization in mehrsprachigen Anwendungen einzusetzen, ohne auf die komfortable Verwaltung Ihrer Schemas direkt im Kotlin-Quellcode verzichten zu müssen.

Da dies die erste Iteration des Protobuf-Schemagenerators ist, hoffen wir stark auf Ihr Feedback. Bitte probieren Sie ihn aus und berichten Sie uns von Ihren Anwendungsfällen, von der Verwaltung Ihrer Modelle und .proto-Dateien, von gefundenen Problemen und von den Funktionen, die Sie eventuell vermissen. Bitte verwenden Sie dazu unseren Issue-Tracker auf GitHub.

Bei der Arbeit mit dem Schemagenerator sollten Sie einige Beschränkungen im Hinterkopf behalten. Als Faustregel gilt Folgendes: Wenn eine Kotlin-Klasse mit der protobuf-Implementierung von kotlinx.serialization serialisiert werden kann, wird sie auch vom Schemagenerator unterstützt. Dies bedeutet gleichzeitig, dass für den Schemagenerator die gleichen Einschränkungen gelten. Hier sind einige Punkte, auf die Sie achten sollten:

• Die Kotlin-Klassen und -Eigenschaftsnamen müssen der protobuf-Spezifikation genügen und dürfen keine unzulässigen Zeichen enthalten.
• Die Nullability in Kotlin wird im Schema nicht dargestellt (da proto2 keine Semantik dafür besitzt). Die von Protocol Buffers bereitgestellten optionalen Felder werden dann verwendet, wenn Ihre Kotlin-Eigenschaften Standardwerte definieren.
• Kotlin-Standardwerte sind nicht im Schema enthalten. (Dies bedeutet, dass Sie selbst für die Einheitlichkeit der Standardwerte in den verschiedenen Sprachimplementierungen sorgen müssen.)

Legen Sie mit kotlinx.serialization 1.2 los!

Damit ist unser Überblick auch schon abgeschlossen. Sind Sie bereit für eine schnellere JSON-Codierung und -Decodierung, Nutzung der Typsystem-Ergänzungen von Kotlin 1.5, die Generierung von Protobuf-Schemas und vieles mehr? Dann ist es Zeit für ein Upgrade!

Wenn Sie kotlinx.serialization bereits verwenden, ist das Upgrade auf Version 1.2 sehr schnell erledigt. Und wenn Sie kotlinx.serialization noch nicht ausprobiert haben, ist dies die perfekte Gelegenheit dazu! Aktualisieren Sie als Erstes den plugins-Abschnitt in Ihrer build.gradle.kts-Datei:

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

Nehmen Sie dann die Laufzeitbibliothek in den dependencies-Abschnitt auf, mit den Formaten, die Sie in Ihrer Anwendung verwenden möchten:

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

Interessantes zum Lesen und Ansehen

• Video zu kotlinx.serialization 1.2
• Die Bibliothek auf GitHub
• Leitfaden zu kotlinx.serialization
• API-Dokumentation
• Blogartikel zur Veröffentlichung von Kotlin 1.5.0

Hilfe bei Problemen

• Bitte melden Sie Probleme in unserem Issue-Tracker auf GitHub.
• Unterstützung finden Sie im #serialization-Kanal des Kotlin-Slacks (eine Einladung erhalten Sie hier).

Abonnieren Sie Kotlin auf YouTube! Viel Spaß beim (De)Serialisieren!