Kotlin Academy · Lektion

Content Negotiation und kotlinx.serialization

Konfigurieren Sie JSON-Serialisierung und deserialisieren Sie Request-Bodies automatisch.

Content Negotiation und kotlinx.serialization ist eine kostenlose Kotlin Academy-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Kotlin Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Kotlin Academy-Kurs umfasst insgesamt 4 Lektionen.

Was ist Content Negotiation?

Content Negotiation ist der HTTP-Mechanismus, über den sich Client und Server auf das Format des Response-Bodys einigen. Der Client sendet einen Accept-Header, und der Server wählt das am besten passende Format. Das Ktor-Plugin ContentNegotiation automatisiert diesen Vorgang.

Abhängigkeiten hinzufügen

Fügen Sie das ContentNegotiation-Plugin und den JSON-Konverter von kotlinx.serialization hinzu:

dependencies {
    implementation("io.ktor:ktor-server-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

ContentNegotiation installieren

Installieren Sie das Plugin in einem Application-Modul und registrieren Sie den JSON-Konverter:

import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

@Serializable-Datenklassen

Annotieren Sie Ihre Datenklassen mit @Serializable aus kotlinx.serialization. Das Kotlin-Compiler-Plugin generiert den Serializer zur Compile-Zeit – zur Laufzeit ist keine Reflection erforderlich:

import kotlinx.serialization.Serializable

@Serializable
data class User(val id: Long, val name: String, val email: String)

Mit einem serialisierbaren Objekt antworten

Sobald ContentNegotiation installiert ist, übergeben Sie jedes @Serializable-Objekt an call.respond(). Ktor serialisiert es automatisch in JSON:

get("/users/{id}") {
    val user = User(1L, "Alice", "alice@example.com")
    call.respond(user)  // serialized to JSON
}

Ein serialisierbares Objekt empfangen

Verwenden Sie call.receive(), um den Request-Body in eine @Serializable-Klasse zu deserialisieren. Wenn der Body fehlerhaft ist, löst Ktor eine ContentTransformationException aus:

post("/users") {
    val newUser = call.receive<User>()
    call.respond(HttpStatusCode.Created, newUser)
}

JSON-Konfiguration anpassen

Übergeben Sie eine Json-Instanz an json(), um die Serialisierung anzupassen: unbekannte Schlüssel ignorieren, Pretty-Printing aktivieren, den lenient-Modus verwenden usw.:

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
    })
}

Mehrere Inhaltstypen

Registrieren Sie mehrere Konverter, um verschiedene Accept-Typen zu unterstützen. Ktor verwendet den ersten Konverter, der zum Accept-Header des Clients passt:

install(ContentNegotiation) {
    json()
    // xml() with ktor-serialization-kotlinx-xml if needed
}

Listen und Maps serialisieren

Verpacken Sie Collections in ein Response-Objekt oder verwenden Sie direkt call.respond(list). kotlinx.serialization verarbeitet List, Map und verschachtelte generische Typen, solange die Elementtypen @Serializable sind:

get("/users") {
    val users = listOf(
        User(1, "Alice", "a@example.com"),
        User(2, "Bob", "b@example.com")
    )
    call.respond(users)
}

Benutzerdefinierte Serializer

Implementieren Sie für Typen, die Sie nicht selbst kontrollieren (z. B. java.time.Instant), einen KSerializer und registrieren Sie ihn über @Serializable(with = MySerializer::class) oder ein Contextual-Serializer-Modul:

val module = SerializersModule {
    contextual(Instant::class, InstantSerializer)
}
install(ContentNegotiation) {
    json(Json { serializersModule = module })
}

Fehlerbehandlung bei fehlgeschlagener Deserialisierung

Installieren Sie das StatusPages-Plugin, um eine saubere Fehlerantwort zurückzugeben, wenn call.receive() fehlschlägt:

install(StatusPages) {
    exception<ContentTransformationException> { call, _ ->
        call.respond(HttpStatusCode.BadRequest, "Invalid request body")
    }
}

Kurzer Check

Welche Annotation ist für eine Kotlin-Datenklasse erforderlich, damit sie von kotlinx.serialization serialisiert werden kann?

Zusammenfassung: Content Negotiation und kotlinx.serialization

Wichtigste Erkenntnisse:

Installieren Sie ContentNegotiation und json() für die automatische JSON-Serialisierung und -Deserialisierung
Annotieren Sie Datenklassen mit @Serializable
Verwenden Sie call.respond(obj) zum Serialisieren und call.receive() zum Deserialisieren
Passen Sie das Verhalten mit einer an json() übergebenen Json { ... }-Instanz an
Verwenden Sie StatusPages, um Deserialisierungsfehler ordnungsgemäß zu behandeln

Häufig gestellte Fragen

Ist die Lektion „Content Negotiation und kotlinx.serialization“ kostenlos?

Ja — der vollständige Text von „Content Negotiation und kotlinx.serialization“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Kotlin Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Kotlin Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Content Negotiation und kotlinx.serialization“?

Konfigurieren Sie JSON-Serialisierung und deserialisieren Sie Request-Bodies automatisch. Du übst Kotlin Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Kotlin Academy zu starten?

Keine Vorkenntnisse erforderlich. Kotlin Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.

Wie lange dauert die Lektion „Content Negotiation und kotlinx.serialization“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Kotlin Academy-Lektion Code schreiben und ausführen?

Ja. Jede Kotlin Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

Ktor-Projekt einrichten: embeddedServer und Application-Module
Routing und typisierte Parameter
Content Negotiation und kotlinx.serialization
Authentifizierungs-Plugins: JWT und Session

← Zurück zu Kotlin Academy