Kotlin Academy · Leçon

Négociation de contenu et kotlinx.serialization

Configurez la sérialisation JSON et désérialisez automatiquement les corps des requêtes.

Leçon 3 sur 413 étapes

Négociation de contenu et kotlinx.serialization est une leçon Kotlin Academy gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Kotlin Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Kotlin Academy comprend 4 leçons au total.

Qu’est-ce que la négociation de contenu ?

La négociation de contenu est le mécanisme HTTP par lequel un client et un serveur conviennent du format du corps de la réponse. Le client envoie un en-tête Accept ; le serveur choisit le format qui correspond le mieux. Le module d’extension Ktor ContentNegotiation automatise ce processus.

Ajout des dépendances

Ajoutez le module d’extension ContentNegotiation ainsi que le convertisseur JSON de 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")
}

Installation de ContentNegotiation

Installez le module d’extension dans un module d’application et enregistrez le convertisseur JSON :

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

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

Classes de données @Serializable

Annotez vos classes de données avec @Serializable de kotlinx.serialization. Le module d’extension du compilateur Kotlin génère le sérialiseur à la compilation — aucune réflexion n’est nécessaire à l’exécution :

import kotlinx.serialization.Serializable

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

Réponse avec un objet sérialisable

Une fois ContentNegotiation installé, transmettez tout objet @Serializable à call.respond(). Ktor le sérialise automatiquement en JSON :

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

Réception d’un objet sérialisable

Utilisez call.receive<T>() pour désérialiser le corps de la requête en une classe @Serializable. Si le corps est mal formé, Ktor lève une ContentTransformationException :

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

Personnalisation de la configuration JSON

Transmettez une instance Json à json() pour personnaliser la sérialisation : ignorez les clés inconnues, activez l’affichage indenté, utilisez le mode permissif, etc. :

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

Plusieurs types de contenu

Enregistrez plusieurs convertisseurs pour prendre en charge différents types Accept. Ktor choisit le premier qui correspond à l’en-tête Accept du client :

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

Sérialisation des listes et des cartes

Entourez les collections d’un objet de réponse ou utilisez directement call.respond(list). kotlinx.serialization gère List<T>, Map<K,V> et les génériques imbriqués, à condition que les types des éléments soient @Serializable :

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

Sérialiseurs personnalisés

Pour les types que vous ne possédez pas (par exemple, java.time.Instant), implémentez un KSerializer<T> et enregistrez-le au moyen de @Serializable(with = MySerializer::class) ou d’un module de sérialiseur contextuel :

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

Gestion des erreurs lors des échecs de désérialisation

Installez le module d’extension StatusPages pour renvoyer une réponse d’erreur claire lorsque call.receive() échoue :

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

Vérification rapide

Quelle annotation faut-il ajouter à une classe de données Kotlin pour qu’elle soit sérialisable avec kotlinx.serialization ?

Réponds-y dans la leçon interactive

Récapitulatif : négociation du contenu et kotlinx.serialization

Points essentiels :

Installez ContentNegotiation et json() pour sérialiser et désérialiser automatiquement au format JSON
Ajoutez l’annotation @Serializable aux classes de données
Utilisez call.respond(obj) pour sérialiser et call.receive() pour désérialiser
Personnalisez le comportement avec une instance Json { ... } transmise à json()
Utilisez StatusPages pour gérer les erreurs de désérialisation avec élégance

Gratuit pour commencer

Apprends Kotlin avec un tuteur IA — gratuit

Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.

Cours: 51
Leçons: 203

Commencer gratuitement Voir le cours complet

Questions Fréquemment Posées

La leçon « Négociation de contenu et kotlinx.serialization » est-elle gratuite ?

Oui — le texte complet de « Négociation de contenu et kotlinx.serialization » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Kotlin Academy, passe à CoddyKit PRO. Le cours Kotlin Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Négociation de contenu et kotlinx.serialization » ?

Configurez la sérialisation JSON et désérialisez automatiquement les corps des requêtes. Tu pratiques Kotlin Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Kotlin Academy ?

Aucune expérience préalable n'est requise. Kotlin Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « Négociation de contenu et kotlinx.serialization » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Kotlin Academy ?

Oui. Chaque leçon Kotlin Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Configuration d’un projet Ktor : embeddedServer et modules d’application
Routage et paramètres typés
Négociation de contenu et kotlinx.serialization
Modules d’authentification : JWT et session

← Retour à Kotlin Academy