Kotlin Academy · Lekcja

Negocjowanie treści i kotlinx.serialization

Skonfiguruj serializację JSON i automatycznie deserializuj treści żądań.

Negocjowanie treści i kotlinx.serialization to bezpłatna lekcja Kotlin Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Kotlin Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Czym jest negocjacja treści

Negocjacja treści to mechanizm HTTP, za pomocą którego klient i serwer uzgadniają format treści odpowiedzi. Klient wysyła nagłówek Accept, a serwer wybiera najlepiej pasujący format. Wtyczka Ktor ContentNegotiation automatyzuje ten proces.

Dodawanie zależności

Należy dodać wtyczkę ContentNegotiation oraz konwerter JSON dla kotlinx.serialization:

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

Instalowanie ContentNegotiation

W module Application należy zainstalować wtyczkę i zarejestrować konwerter JSON:

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

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

Klasy danych @Serializable

Klasy danych należy oznaczyć adnotacją @Serializable z kotlinx.serialization. Wtyczka kompilatora Kotlin generuje serializator podczas kompilacji — w czasie działania nie jest potrzebna refleksja:

import kotlinx.serialization.Serializable

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

Odpowiadanie obiektem serializowalnym

Po zainstalowaniu ContentNegotiation dowolny obiekt @Serializable można przekazać do call.respond(). Ktor automatycznie serializuje go do JSON:

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

Odbieranie obiektu serializowalnego

Za pomocą call.receive<T>() można zdeserializować treść żądania do klasy @Serializable. Jeśli treść jest niepoprawnie sformatowana, Ktor zgłasza wyjątek ContentTransformationException:

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

Dostosowywanie konfiguracji JSON

Instancję Json należy przekazać do json(), aby dostosować serializację: ignorować nieznane klucze, formatować JSON w czytelny sposób, używać trybu pobłażliwego itd.:

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

Wiele typów treści

Należy zarejestrować wiele konwerterów, aby obsługiwać różne typy Accept. Ktor wybiera pierwszy konwerter pasujący do nagłówka Accept klienta:

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

Serializowanie list i map

Kolekcje można umieścić w obiekcie odpowiedzi albo użyć bezpośrednio call.respond(list). kotlinx.serialization obsługuje List<T>, Map<K,V> oraz zagnieżdżone typy generyczne, o ile typy elementów są oznaczone adnotacją @Serializable:

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

Niestandardowe serializatory

W przypadku typów, których nie kontroluje się (np. java.time.Instant), należy zaimplementować KSerializer<T> i zarejestrować go za pomocą @Serializable(with = MySerializer::class) albo modułu serializatorów kontekstowych:

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

Obsługa błędów deserializacji

Zainstaluj wtyczkę StatusPages, aby zwracać przejrzystą odpowiedź błędu, gdy wywołanie call.receive() zakończy się niepowodzeniem:

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

Szybkie sprawdzenie

Jaka adnotacja jest wymagana w klasie danych Kotlin, aby można było ją serializować za pomocą kotlinx.serialization?

Podsumowanie: Content Negotiation i kotlinx.serialization

Najważniejsze informacje:

Zainstaluj ContentNegotiation oraz json(), aby włączyć automatyczną serializację i deserializację JSON
Oznacz klasy danych adnotacją @Serializable
Użyj call.respond(obj) do serializacji oraz call.receive() do deserializacji
Dostosuj działanie za pomocą instancji Json { ... } przekazanej do json()
Użyj StatusPages, aby poprawnie obsługiwać błędy deserializacji

Często zadawane pytania

Czy lekcja „Negocjowanie treści i kotlinx.serialization” jest bezpłatna?

Tak — pełny tekst „Negocjowanie treści i kotlinx.serialization” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Kotlin Academy, przejdź na CoddyKit PRO. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Negocjowanie treści i kotlinx.serialization”?

Skonfiguruj serializację JSON i automatycznie deserializuj treści żądań. Ćwiczysz Kotlin Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Kotlin Academy?

Nie wymagamy żadnego doświadczenia. Kotlin Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Negocjowanie treści i kotlinx.serialization”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Kotlin Academy?

Tak. Każda lekcja Kotlin Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Konfiguracja projektu Ktor: embeddedServer i moduły Application
Routing i typowane parametry
Negocjowanie treści i kotlinx.serialization
Wtyczki uwierzytelniania: JWT i sesje

← Powrót do Kotlin Academy