Moshi: Schlüsselkonzepte, JSON-Bibliothek für Kotlin und Funktionsweise

Was ist Moshi

Moshi ist eine JSON-Bibliothek für JVM, Android und Kotlin Multiplatform, entwickelt von Square (den Autoren von OkHttp und Retrofit). Im Gegensatz zu Gson verlässt sich Moshi nicht auf Reflektion — die Adapter werden zur Kompilierzeit über die Annotation @JsonClass(generateAdapter = true) generiert. Das macht Moshi schneller, sicherer und vorhersagbarer bei der Arbeit mit Kotlin-spezifischen Konstrukten.

Philosophie und Vorteile

Der Hauptunterschied zwischen Moshi und seinen Vorgängern ist die Ablehnung von Reflektion. Reflektion ermöglicht es Gson, ohne Vorbereitung mit jeder Klasse zu arbeiten, aber der Preis ist eine langsame Initialisierung, die Unmöglichkeit der Optimierung durch den Compiler und das Risiko von Laufzeitfehlern. Moshi erfordert eine explizite Klassendeklaration für die Codegenerierung, bietet dafür aber die Geschwindigkeit von handgeschriebenem Code und vollständige Typsicherheit zur Kompilierzeit.

// Moshi zu build.gradle hinzufügen
dependencies {
    implementation "com.squareup.moshi:moshi:1.15.0"
    implementation "com.squareup.moshi:moshi-kotlin:1.15.0"
    kapt "com.squareup.moshi:moshi-kotlin-codegen:1.15.0"
}

// Einfaches Modell mit Codegenerierung
@JsonClass(generateAdapter = true)
data class User(
    @Json(name = "user_id")
    val id: Int,
    val name: String,
    val email: String,
    val avatar: String? = null
)

// Verwendung
val moshi = Moshi.Builder()
    .build()
val jsonAdapter = moshi.adapter(User::class.java)

Installation und Konfiguration

Um mit Moshi zu arbeiten, müssen Abhängigkeiten zur build.gradle hinzugefügt und die Modelle annotiert werden. Moshi.Builder dient als Einstiegspunkt: über ihn werden integrierte Adapter für Standardtypen, benutzerdefinierte Adapter hinzugefügt und das Verhalten der Bibliothek konfiguriert. Moshi unterstützt Adapter für Date, Enum, Collection und Map standardmäßig, aber Kotlin-Klassen benötigen das Modul moshi-kotlin. Im Gegensatz zu Gson verwendet Moshi standardmäßig keine Reflektion für Kotlin-Klassen — dafür wird KotlinJsonAdapterFactory eingebunden, der als Fallback dient, wenn keine Codegenerierung verwendet wird oder die Klasse nicht mit @JsonClass annotiert ist. Dieser Ansatz stellt sicher, dass der Entwickler für jede spezifische Klasse explizit zwischen der Leistung der Codegenerierung und der Flexibilität der Reflektion wählt.

Moshi erstellen und Adapter hinzufügen

Nachdem Moshi über den Builder erstellt wurde, erhält der Entwickler eine Moshi-Instanz und fordert einen Adapter für die gewünschte Klasse an. JsonAdapter ist das zentrale Objekt, das die Serialisierung über toJson() und die Deserialisierung über fromJson() durchführt. Moshi verwendet automatisch den generierten Adapter, wenn die Klasse mit @JsonClass(generateAdapter = true) annotiert ist, andernfalls wird der reflektierende KotlinJsonAdapterFactory als Fallback angewendet. Dieser Ansatz kombiniert die Geschwindigkeit der Codegenerierung mit der Flexibilität eines reflektierenden Mechanismus für Projekte jeder Größenordnung und Komplexität. Moshi eignet sich sowohl für kleine Anwendungen als auch für große Unternehmensprojekte mit Hunderten von Datenmodellen.

// Moshi mit KotlinJsonAdapterFactory konfigurieren
val moshi = Moshi.Builder()
    .add(KotlinJsonAdapterFactory())
    .add(LocalDateAdapter())
    .build()

// Adapter verwenden
val adapter = moshi.adapter(User::class.java)

// Serialisierung
val user = User(1, "Alice", "alice@test.com")
val json = adapter.toJson(user)

// Deserialisierung
val jsonString = """{"user_id":2,"name":"Bob","email":"bob@test.com"}"""
val parsedUser = adapter.fromJson(jsonString)

// Mit Listen arbeiten
val listAdapter = moshi.adapter(
    Types.newParameterizedType(
        List::class.java,
        User::class.java
    )
)

Annotationen und Adapter

Moshi verwendet Annotationen zur Konfiguration der Serialisierung und zur Unterstützung benutzerdefinierter Typen. @Json(name = "...") legt den JSON-Schlüssel für ein Feld fest. @Transient schließt ein Feld von der Serialisierung aus. @JsonClass(generateAdapter = true) aktiviert die Codegenerierung. Für benutzerdefinierte Logik stellt Moshi die Annotationen @ToJson und @FromJson bereit, die in einer separaten Adapterklasse platziert werden können.

@Json und benutzerdefinierte Adapter

Die @Json-Annotation ersetzt Gsons @SerializedName und funktioniert ähnlich: das Feld kotlinName wird mit dem JSON-Schlüssel „kotlin_name“ verknüpft. Für Typen, die Moshi standardmäßig nicht serialisieren kann (z.B. LocalDate), erstellt der Entwickler eine Klasse mit @ToJson- und @FromJson-Methoden. Adapter werden über Moshi.Builder.add() registriert und global oder für einen bestimmten Typ angewendet. Moshi unterstützt versiegelte Klassen und polymorphe Serialisierung über @JsonClass mit einem expliziten Diskriminator, was die Arbeit mit Typhierarchien in JSON ohne manuelle Feldüberprüfung ermöglicht. Bei der Deserialisierung ignoriert Moshi standardmäßig unbekannte JSON-Schlüssel, was die Abwärtskompatibilität beim Hinzufügen neuer Felder auf der Serverseite ohne Änderung des Client-Codes gewährleistet. Zum Debuggen kann der strenge Modus über failOnUnknown aktiviert werden, der eine Ausnahme auslöst, wenn unbekannte Schlüssel gefunden werden.

// Benutzerdefinierter Adapter für LocalDate
class LocalDateAdapter {

    @ToJson
    fun toJson(date: LocalDate): String {
        return date.format(DateTimeFormatter.ISO_LOCAL_DATE)
    }

    @FromJson
    fun fromJson(dateString: String): LocalDate {
        return LocalDate.parse(dateString)
    }
}

// Modell mit Moshi-Annotationen
@JsonClass(generateAdapter = true)
data class Event(
    @Json(name = "event_id")
    val id: Int,

    @Json(name = "event_date")
    val date: LocalDate,

    @Transient
    val localCache: String? = null
)

// Adapter registrieren
val moshi = Moshi.Builder()
    .add(LocalDateAdapter())
    .add(KotlinJsonAdapterFactory())
    .build()

Moshi vs Gson

Der Vergleich von Moshi und Gson ist eine häufige Frage bei der Wahl einer JSON-Bibliothek für ein Android-Projekt. Moshi punktet in der modernen Kotlin-Entwicklung dank Codegenerierung, Nullsicherheit und Geschwindigkeit. Gson bleibt für Java-Projekte, Legacy-Code und Szenarien relevant, in denen eine minimale Konfiguration wichtig ist. Der Unterschied wird bei großen Datenmengen und komplexen Modellen deutlich.

Leistung und Sicherheit

Leistungstests zeigen, dass Moshi mit Codegenerierung bei Serialisierungs- und Deserialisierungsvorgängen 2–5 Mal schneller ist als Gson. Der Hauptvorteil von Moshi ist die korrekte Handhabung der Nullsicherheit von Kotlin: Fehlt ein Feld im JSON und das Modell deklariert es als non-null ohne Standardwert, löst Moshi eine Ausnahme bei der Deserialisierung aus und verhindert so versteckte Fehler.

Die Wahl zwischen Moshi und Gson hängt vom Projektkontext ab. Neue Kotlin-Projekte profitieren von Moshi dank Typsicherheit und Leistung. Gson bleibt eine vernünftige Wahl zur Unterstützung von Java-Code, dynamischen JSON-Strukturen oder wenn die Einfachheit der Einrichtung wichtiger ist als die Geschwindigkeit. Für Kotlin Multiplatform ist Moshi die einzige der beiden Optionen, die diese Plattform unterstützt.

Bei der Migration von Gson zu Moshi betreffen die Hauptänderungen Annotationen und Adapter. Gsons @SerializedName wird durch @Json(name = "...") ersetzt und benutzerdefinierte JsonSerializer/JsonDeserializer durch das Paar @ToJson/@FromJson. Bei Modellen mit Standardwerten und nullable-Feldern verhält sich Moshi vorhersagbarer: Fehlt ein non-null-Feld ohne Standardwert im JSON, löst Moshi eine JsonDataException aus und verhindert versteckte NPEs. Die Integration mit Retrofit über MoshiConverterFactory wird mit einer einzigen Abhängigkeit hinzugefügt und erfordert keine Änderung der Netzwerkschichtarchitektur. Für die Verschleierung durch ProGuard oder R8 müssen Regeln hinzugefügt werden, um mit @JsonClass annotierte Klassen und generierte Adapter zu erhalten, andernfalls bricht die Serialisierung im Release-Build zusammen. Insgesamt ist die Migration von Gson zu Moshi in neuen Kotlin-Projekten gerechtfertigt, in denen Leistung und Typsicherheit wichtig sind.

// Serialisierungsvergleich: Gson vs Moshi
data class Sample(
    val name: String,
    val count: Int,
    val tags: List<String> = listOf()
)

// Gson: arbeitet über Reflektion
val gson = Gson()
val fromGson = gson.fromJson("""{"name":"test"}""",
    Sample::class.java)
// count = 0 (Standard), aber Nullsicherheit wird nicht geprüft

// Moshi: benötigt einen Adapter, Nullsicherheit ist explizit
@JsonClass(generateAdapter = true)
data class SampleMoshi(
    val name: String,
    val count: Int,
    val tags: List<String> = listOf()
)