Gson-Bug: Warum fehlende @SerializedName zu Null-Werten führt

Ein Kollege in Ihrem Entwicklerteam hat kürzlich eine scheinbar harmlose Codebereinigung vorgenommen. Das Ziel: Redundante Annotationen entfernen, um den Quelltext sauberer zu gestalten. Doch was wie eine harmlose Optimierung wirkte, führte zu einem schwerwiegenden Fehler in der Anwendung. Plötzlich zeigten alle Pokémon in der Datenbank einen Basis-Stat-Status von 0 an – obwohl die API korrekte Werte lieferte. Verwirrend: Gson, die Bibliothek zur JSON-Verarbeitung, meldete keinen Fehler, keine Warnung, kein einziges Zeichen.

Die Ursache: Gson sucht exakte Namensgleichheit

Gson, die beliebte Java/Kotlin-Bibliothek zur Serialisierung und Deserialisierung von JSON-Daten, funktioniert nach einem einfachen, aber strikten Prinzip: Sie vergleicht JSON-Schlüssel mit den Eigenschaftsnamen der Kotlin-Klasse. Nur wenn die Namen exakt übereinstimmen, wird ein Wert zugewiesen. Andernfalls bleibt die Eigenschaft auf ihrem Standardwert – und das völlig geräuschlos.

Nehmen wir das folgende Beispiel aus einem Pokémon-Statistik-Modell:

data class PokemonStat(
    @SerializedName("base_stat") val baseStat: Int,
    val stat: StatInfo
)

Hier wird die Annotation @SerializedName("base_stat") verwendet, um den JSON-Schlüssel base_stat mit der Kotlin-Eigenschaft baseStat zu verknüpfen. Entfernt man nun diese Annotation, weil sie als redundant erscheint, ändert sich der Name der Kotlin-Eigenschaft zu baseStat. Gson sucht nun nach einem JSON-Schlüssel namens baseStat – findet ihn nicht und setzt den Wert der Eigenschaft stattdessen auf den Standardwert für Int, also 0.

Warum bleibt Gson stumm?

Der entscheidende Punkt: Gson behandelt fehlende JSON-Schlüssel nicht als Fehler. Stattdessen füllt es die Klasse mit den gefundenen Werten und belässt die restlichen Eigenschaften auf ihren Standardwerten. Dieses Verhalten ähnelt dem Ausfüllen eines Formulars: Eine leere Zeile ist kein Grund, das Formular abzulehnen. Gson akzeptiert fehlende Schlüssel einfach – ohne Warnung, ohne Log, ohne Ausnahme.

Die Standardwerte für verschiedene Datentypen in Kotlin sind:

• Int, Long: 0
• Double, Float: 0.0
• Boolean: false
• String, komplexe Objekte, List: null

Ein fehlender Schlüssel führt also dazu, dass eine Eigenschaft den Wert 0 oder null erhält – ohne dass Gson dies als Problem markiert. Erst bei der späteren Verwendung der Daten wird der Fehler sichtbar, etwa wenn ein Int-Wert als 0 interpretiert wird oder eine String-Eigenschaft plötzlich null ist.

Wann wirft Gson tatsächlich eine Ausnahme?

Gson ist zwar nachsichtig bei fehlenden Schlüsseln, aber streng bei zwei anderen Szenarien:

• Ungültiges JSON: Wenn die JSON-Struktur beschädigt ist – etwa durch fehlende Klammern oder falsche Syntax – wirft Gson eine Ausnahme.
• Typfehler: Wenn ein JSON-Schlüssel einen Wert enthält, der nicht zum erwarteten Datentyp passt, etwa ein String statt eines Int, wirft Gson eine Ausnahme.

Ein leerer Schlüssel ist also kein Problem. Ein fehlender Wert oder ein falscher Typ hingegen schon. Diese Unterscheidung ist entscheidend, um Gson effektiv zu nutzen.

Das Risiko: Gson ignoriert Kotlins Null-Sicherheit

Kotlin ist bekannt für seine Null-Sicherheit – ein zentrales Versprechen der Sprache. Eine Eigenschaft, die als val name: String deklariert wird, darf niemals null sein. Der Compiler erzwingt diese Garantie, und Entwickler müssen sich keine Sorgen über NullPointerException-Fehler machen.

Doch Gson umgeht diese Garantie auf subtile Weise. Statt die Eigenschaften wie gewohnt zu initialisieren, nutzt Gson Reflection, um Werte direkt in die Felder zu schreiben. Dabei ignoriert die Bibliothek Kotlins Null-Sicherheit vollständig. Wenn ein JSON-Schlüssel fehlt, setzt Gson einfach null in eine Eigenschaft ein, die explizit als nicht-null deklariert wurde – ohne Warnung, ohne Fehler.

Später, wenn der Code versucht, auf diese Eigenschaft zuzugreifen, etwa mit name.length, führt dies zu einer NullPointerException. Der Fehler tritt jedoch weit entfernt von der JSON-Verarbeitung auf, was die Fehlersuche extrem erschwert.

Die Lösung: Nullable Typen für JSON-Felder

Um dieses Risiko zu vermeiden, sollten Entwickler JSON-Felder explizit als nullable deklarieren, wenn die API diese Felder möglicherweise auslässt. So wird Kotlins Null-Sicherheit gewahrt:

data class Sprites(
    @SerializedName("front_default") val frontDefault: String?
)

Durch das Hinzufügen des ? wird Kotlin darauf hingewiesen, dass der Wert null sein könnte. Der Compiler erzwingt dann, dass Entwickler den Fall null explizit behandeln – bevor es zu einem Absturz kommt.

Fazit: Bewusstsein schafft sichere JSON-Verarbeitung

Der stille Bug in Gson ist ein Beispiel dafür, wie eine scheinbar kleine Codeänderung zu schwerwiegenden Konsequenzen führen kann. Die Bibliothek behandelt fehlende Schlüssel nicht als Fehler, sondern setzt Standardwerte ein – ein Verhalten, das Entwickler kennen und verstehen müssen. Gleichzeitig ignoriert Gson Kotlins Null-Sicherheit, was zu subtilen und schwer zu debuggenden Fehlern führen kann.

Wenn Sie Gson in Ihren Projekten einsetzen, achten Sie darauf, alle JSON-Schlüssel explizit zu mappen und nullable Typen zu verwenden, um Kotlins Sicherheitsmechanismen nicht zu untergraben. Nur so können Sie sicherstellen, dass Ihre Anwendung auch in komplexen Szenarien fehlerfrei funktioniert.