Kotlin Academy · Lezione

Content negotiation e kotlinx.serialization

Configuri la serializzazione JSON e deserializzi automaticamente i body delle richieste.

Lezione 3 di 413 passaggi

Content negotiation e kotlinx.serialization è una lezione Kotlin Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Kotlin Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Kotlin Academy include 4 lezioni in totale.

Che cos'è la content negotiation?

La content negotiation è il meccanismo HTTP attraverso il quale client e server concordano il formato del corpo della risposta. Il client invia un'intestazione Accept; il server sceglie il formato più adatto tra quelli compatibili. Il plugin ContentNegotiation di Ktor automatizza questo processo.

Aggiunta delle dipendenze

Aggiunga il plugin ContentNegotiation e il convertitore JSON di 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")
}

Installazione di ContentNegotiation

Installi il plugin in un modulo Application e registri il convertitore JSON:

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

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

Classi di dati @Serializable

Annoti le classi di dati con @Serializable di kotlinx.serialization. Il plugin del compilatore Kotlin genera il serializzatore in fase di compilazione: non è necessaria la reflection in fase di runtime:

import kotlinx.serialization.Serializable

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

Risposta con un oggetto serializzabile

Una volta installato ContentNegotiation, passi qualsiasi oggetto @Serializable a call.respond(). Ktor lo serializza automaticamente in JSON:

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

Ricezione di un oggetto serializzabile

Utilizzi call.receive() per deserializzare il corpo della richiesta in una classe @Serializable. Se il corpo non è valido, Ktor genera una ContentTransformationException:

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

Personalizzazione della configurazione JSON

Passi un'istanza di Json a json() per personalizzare la serializzazione: ignori le chiavi sconosciute, abiliti il pretty-print, utilizzi la modalità lenient e così via:

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

Più tipi di contenuto

Registri più convertitori per supportare diversi tipi Accept. Ktor sceglie il primo che corrisponde all'intestazione Accept del client:

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

Serializzazione di liste e mappe

Racchiuda le collezioni in un oggetto di risposta oppure utilizzi direttamente call.respond(list). kotlinx.serialization gestisce List, Map e i generics annidati, purché i tipi degli elementi siano @Serializable:

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

Serializzatori personalizzati

Per i tipi che non possiede (ad esempio java.time.Instant), implementi un KSerializer e lo registri tramite @Serializable(with = MySerializer::class) o mediante un modulo di serializzazione contestuale:

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

Gestione degli errori di deserializzazione

Installi il plugin StatusPages per restituire una risposta di errore chiara quando call.receive() non riesce:

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

Verifica rapida

Quale annotazione è necessaria su una data class Kotlin affinché possa essere serializzata da kotlinx.serialization?

Rispondi nella lezione interattiva

Riepilogo: Content Negotiation e kotlinx.serialization

Punti chiave:

Installi ContentNegotiation + json() per la serializzazione/deserializzazione automatica in JSON
Annoti le data class con @Serializable
Utilizzi call.respond(obj) per serializzare e call.receive() per deserializzare
Personalizzi il comportamento con un'istanza Json { ... } passata a json()
Utilizzi StatusPages per gestire elegantemente gli errori di deserializzazione

Gratis per iniziare

Impara Kotlin con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 51
Lezioni: 203

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Content negotiation e kotlinx.serialization» è gratuita?

Sì — il testo completo di «Content negotiation e kotlinx.serialization» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Kotlin Academy, passa a CoddyKit PRO. Il corso Kotlin Academy include 4 lezioni in totale.

Cosa imparerò in «Content negotiation e kotlinx.serialization»?

Configuri la serializzazione JSON e deserializzi automaticamente i body delle richieste. Eserciti Kotlin Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Kotlin Academy?

Non è richiesta alcuna esperienza precedente. Kotlin Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Content negotiation e kotlinx.serialization»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Kotlin Academy?

Sì. Ogni lezione Kotlin Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Configurazione di un progetto Ktor: embeddedServer e moduli Application
Routing e parametri tipizzati
Content negotiation e kotlinx.serialization
Plugin di autenticazione: JWT e sessione

← Torna a Kotlin Academy