Moshi: kernconcepten, JSON Kotlin-bibliotheek en hoe het werkt

Wat is Moshi

Moshi is een JSON-bibliotheek voor JVM, Android en Kotlin Multiplatform, gemaakt door Square (makers van OkHttp en Retrofit). In tegenstelling tot Gson vertrouwt Moshi niet op reflectie — adapters worden gegenereerd tijdens de compilatiefase via de annotatie @JsonClass(generateAdapter = true). Dit maakt Moshi sneller, veiliger en voorspelbaarder in het werken met Kotlin-specifieke constructies.

Filosofie en voordelen

Het belangrijkste verschil van Moshi met voorgangers is het afzien van reflectie. Reflectie stelt Gson in staat om zonder voorbereiding met elke klasse te werken, maar de prijs is trage initialisatie, onmogelijkheid van optimalisatie door de compiler en risico op fouten tijdens runtime. Moshi vereist expliciete aanduiding van klassen voor codegeneratie, maar geeft daarvoor in de plaats de snelheid van handgeschreven code en volledige typeveiligheid tijdens de compilatiefase.

// Moshi aansluiten in build.gradle
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"
}

// Eenvoudig model met codegeneratie
@JsonClass(generateAdapter = true)
data class User(
    @Json(name = "user_id")
    val id: Int,
    val name: String,
    val email: String,
    val avatar: String? = null
)

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

Installatie en configuratie

Om met Moshi te beginnen, moeten afhankelijkheden worden toegevoegd in build.gradle en modellen worden geannoteerd. Moshi.Builder dient als ingangspunt: via hem worden ingebouwde adapters voor standaardtypen, aangepaste adapters toegevoegd en het gedrag van de bibliotheek geconfigureerd. Moshi ondersteunt adapters voor Date, Enum, Collection en Map uit de doos, maar voor Kotlin-klassen is de moshi-kotlin-module vereist. In tegenstelling tot Gson gebruikt Moshi standaard geen reflectie voor Kotlin-klassen — hiervoor wordt KotlinJsonAdapterFactory aangesloten, die als reserveoptie dient wanneer codegeneratie niet wordt toegepast of de klasse niet is geannoteerd met @JsonClass. Deze aanpak garandeert dat de ontwikkelaar expliciet kiest tussen de prestaties van codegeneratie en de flexibiliteit van reflectie voor elke specifieke klasse.

Moshi maken en adapters toevoegen

Na het bouwen van Moshi via Builder krijgt de ontwikkelaar een Moshi-instantie en vraagt een adapter aan voor de gewenste klasse. JsonAdapter is het centrale object dat serialisatie uitvoert via toJson() en deserialisatie via fromJson(). Moshi gebruikt automatisch de gegenereerde adapter als de klasse is geannoteerd met @JsonClass(generateAdapter = true), anders past het reflectieve KotlinJsonAdapterFactory toe als reserveoptie. Deze aanpak combineert de snelheid van codegeneratie met de flexibiliteit van het reflectieve mechanisme voor projecten van elke schaal en complexiteit. Moshi is geschikt voor zowel kleine applicaties als grote bedrijfsprojecten met honderden datamodellen.

// Moshi configureren met KotlinJsonAdapterFactory
val moshi = Moshi.Builder()
    .add(KotlinJsonAdapterFactory())
    .add(LocalDateAdapter())
    .build()

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

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

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

// Werken met lijst
val listAdapter = moshi.adapter(
    Types.newParameterizedType(
        List::class.java,
        User::class.java
    )
)

Annotaties en adapters

Moshi gebruikt annotaties voor het configureren van serialisatie en ondersteuning van aangepaste typen. @Json(name = "...") stelt de JSON-sleutel voor een veld in. @Transient sluit een veld uit van serialisatie. @JsonClass(generateAdapter = true) schakelt codegeneratie in. Voor aangepaste logica biedt Moshi de annotaties @ToJson en @FromJson, die in een aparte adapterklasse kunnen worden geplaatst.

@Json en aangepaste adapters

De annotatie @Json vervangt de Gson @SerializedName en werkt vergelijkbaar: het veld kotlinName wordt gekoppeld aan de JSON-sleutel “kotlin_name”. Voor typen die Moshi standaard niet kan serialiseren (bijv. LocalDate), maakt de ontwikkelaar een klasse met methoden @ToJson en @FromJson. Adapters worden geregistreerd via Moshi.Builder.add() en globaal of voor een specifiek type toegepast. Moshi ondersteunt sealed class en polymorfe serialisatie via @JsonClass met expliciete aanduiding van een discriminator, wat werken met typehiërarchieën in JSON mogelijk maakt zonder handmatige veldcontrole. Bij deserialisatie negeert Moshi standaard onbekende sleutels in JSON, wat achterwaartse compatibiliteit biedt bij het toevoegen van nieuwe velden aan de serverzijde zonder wijziging van de clientcode. Voor debugging kan de strikte modus worden ingeschakeld via failOnUnknown, die een uitzondering gooit bij detectie van onbekende sleutels.

// Aangepaste adapter voor 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)
    }
}

// Model met Moshi-annotaties
@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 registreren
val moshi = Moshi.Builder()
    .add(LocalDateAdapter())
    .add(KotlinJsonAdapterFactory())
    .build()

Moshi vs Gson

Vergelijking van Moshi en Gson is een veelgestelde vraag bij het kiezen van een JSON-bibliotheek voor een Android-project. Moshi wint in moderne Kotlin-ontwikkeling dankzij codegeneratie, null-veiligheid en snelheid. Gson blijft relevant voor Java-projecten, legacy-code en scenario's waar minimale configuratie belangrijk is. Het verschil wordt merkbaar bij grote hoeveelheden gegevens en complexe modellen.

Prestaties en veiligheid

Prestatietests tonen aan dat Moshi met codegeneratie 2-5 keer sneller werkt dan Gson bij serialisatie- en deserialisatiebewerkingen. Het belangrijkste voordeel van Moshi is de correcte afhandeling van Kotlin null-veiligheid: als een veld ontbreekt in JSON en in het model is gedeclareerd als non-null zonder standaardwaarde, gooit Moshi een uitzondering tijdens deserialisatie, waardoor verborgen fouten worden voorkomen.

De keuze tussen Moshi en Gson hangt af van de projectcontext. Nieuwe projecten op Kotlin profiteren van Moshi vanwege typeveiligheid en prestaties. Gson blijft een redelijke keuze voor ondersteuning van Java-code, dynamische JSON-structuren of wanneer eenvoud van aansluiting belangrijker is dan snelheid. Voor Kotlin Multiplatform is Moshi de enige van de twee varianten die dit platform ondersteunt.

Bij migratie van Gson naar Moshi betreffen de belangrijkste wijzigingen annotaties en adapters. Gson's @SerializedName wordt vervangen door @Json(name = "...") en aangepaste JsonSerializer/JsonDeserializer door het paar @ToJson/@FromJson. Voor modellen met standaardwaarden en nullable-velden gedraagt Moshi zich voorspelbaarder: als een non-null veld zonder standaardwaarde ontbreekt in JSON, gooit Moshi een JsonDataException, waardoor verborgen NPE's worden voorkomen. Integratie met Retrofit via MoshiConverterFactory wordt met één afhankelijkheid toegevoegd en vereist geen wijziging van de netwerklaagarchitectuur. Voor obfuscatie via ProGuard of R8 moeten regels worden toegevoegd voor het behoud van @JsonClass-geannoteerde klassen en gegenereerde adapters, anders zal serialisatie breken in de release-build. Over het algemeen is migratie van Gson naar Moshi gerechtvaardigd in nieuwe Kotlin-projecten waar prestaties en typeveiligheid belangrijk zijn.

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

// Gson: werkt via reflectie
val gson = Gson()
val fromGson = gson.fromJson("""{"name":"test"}""",
    Sample::class.java)
// count = 0 (default), maar null-veiligheid wordt niet gecontroleerd

// Moshi: vereist adapter, null-veiligheid is expliciet
@JsonClass(generateAdapter = true)
data class SampleMoshi(
    val name: String,
    val count: Int,
    val tags: List<String> = listOf()
)