Ktor: qu'est-ce que c'est, caractéristiques du client HTTP asynchrone

Qu'est-ce que Ktor ?

Ktor est un framework pour construire des applications asynchrones serveur et client en Kotlin, créé par JetBrains. Ktor Client est la partie cliente du framework, fournissant un client HTTP avec un support complet des coroutines Kotlin, du multiplateforme (JVM, Native, JS) et une architecture modulaire basée sur des plugins.

Ktor est apparu en 2018 comme alternative à Retrofit et OkHttp pour les projets Kotlin-first. Contrairement à Retrofit, qui a porté l'approche Java avec des annotations, Ktor Client utilise Kotlin DSL pour la configuration des requêtes — sans annotations ni réflexion. Cela rend le code plus lisible et type-safe pour les développeurs Kotlin.

Selon l'enquête Kotlin Multiplatform 2024, Ktor Client est utilisé dans 35% des projets Kotlin Multiplatform Mobile (KMM), ce qui en fait le deuxième client HTTP le plus populaire après OkHttp dans la communauté Kotlin. Ktor est préféré dans les projets où le support multiplateforme et l'intégration native avec l'écosystème Kotlin sont importants.

Comment fonctionne Ktor Client

L'architecture de Ktor Client est basée sur un pipeline de plugins. Chaque requête traverse une séquence de plugins installés qui peuvent modifier la requête, la réponse ou effectuer des actions secondaires — journalisation, compression, sérialisation, authentification.

Lors de la création d'un client HTTP via le bloc DSL HttpClient { }, vous spécifiez le moteur (OkHttp, Android, CIO, Darwin) et installez les plugins. Chaque moteur implémente l'envoi de requêtes de bas niveau pour une plateforme spécifique : sur Android, le moteur OkHttp est utilisé, sur iOS — Darwin (URLSession), sur Desktop — CIO (Coroutine I/O). HttpClient sélectionne automatiquement le moteur optimal pour la plateforme actuelle.

Une requête dans Ktor Client est exécutée via une fonction suspend, ce qui signifie une intégration complète avec les coroutines. Pas de Callbacks, pas de RxJava ou LiveData — seulement du code séquentiel avec suspend qui fonctionne de manière asynchrone sans bloquer le thread.

Pipeline de traitement des requêtes

Le pipeline Ktor se compose de phases : d'abord la requête traverse les plugins installés (par exemple, ContentNegotiation pour JSON, Logging pour les journaux), puis le moteur exécute la requête HTTP, et la réponse traverse à nouveau les plugins pour la désérialisation. Chaque plugin est une fonction suspend s'exécutant dans la coroutine du pipeline.

Un avantage important du pipeline Ktor est la capacité d'effectuer un traitement conditionnel. Un plugin peut vérifier l'URL ou les en-têtes de la requête et ignorer le traitement si la condition n'est pas remplie. Par exemple, ContentEncoding avec gzip est uniquement appliqué aux réponses contenant l'en-tête Content-Encoding: gzip, et Auth ne se déclenche que pour les endpoints protégés sans affecter les API publiques.

Cette approche de pipeline permet de combiner les plugins de manière flexible : vous pouvez installer ContentNegotiation avec JSON, ajouter Auth avec un token Bearer, activer la compression ContentEncoding et HttpTimeout — et tous fonctionneront ensemble dans le bon ordre. L'ordre d'installation des plugins est important : le premier plugin installé traitera la requête avant les autres.

Plugins Ktor Client

Les plugins sont le système d'extension modulaire de Ktor, remplaçant les annotations de Retrofit et les intercepteurs d'OkHttp. Chaque plugin résout une tâche spécifique et est installé via la fonction install() dans le bloc HttpClient. Ktor fournit des plugins intégrés et permet également d'en créer des personnalisés.

Plugins personnalisés

Pour des tâches spécifiques, un plugin personnalisé est créé via createClientPlugin. Le plugin peut intercepter la requête (onRequest), la réponse (onResponse) ou gérer les erreurs (onError). Cela remplace complètement l'Interceptor d'OkHttp, mais avec une API Kotlin typée et le support des fonctions suspend.

Les plugins personnalisés sont pratiques pour ajouter des métriques, une logique de réessai automatique, du traçage de requêtes ou des tests A/B d'endpoints. Contrairement aux intercepteurs d'OkHttp, les plugins Ktor sont écrits en Kotlin et s'exécutent dans le contexte de la coroutine, simplifiant la gestion des erreurs et des timeouts.

Pour le débogage des requêtes, le plugin Logging est utilisé avec le niveau ALL, HEADERS ou BODY. Logging affiche la méthode, l'URL, le statut, les en-têtes et le corps de la requête et de la réponse. Contrairement à HttpLoggingInterceptor d'OkHttp, Ktor Logging fonctionne de manière asynchrone et peut être configuré pour filtrer par niveau de log (ERROR, WARN, INFO, DEBUG) sans arrêter l'application pour changer la configuration.

Exemples de code Ktor Client en Kotlin

Examinons une requête GET de base avec Ktor Client. Un HttpClient est créé avec le plugin ContentNegotiation installé pour JSON. La requête est exécutée via la fonction suspend get(), et le résultat est automatiquement désérialisé dans une data class.

data class User(
    val login: String,
    val id: Int,
    val avatarUrl: String
)

val client = HttpClient {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun getUser(): User {
    return client.get("https://api.github.com/users/octocat").body()
}

Pour une requête POST avec corps, la fonction post() est utilisée avec contentType() et body(). Ktor sérialise automatiquement l'objet en JSON via ContentNegotiation installé. Le style DSL rend le code séquentiel et lisible.

data class CreateRepo(
    val name: String,
    val description: String,
    val private: Boolean
)

suspend fun createRepo(): Unit {
    val repo = CreateRepo(
        name = "my-project",
        description = "Sample project",
        private = false
    )
    client.post("https://api.github.com/user/repos") {
        contentType(ContentType.Application.Json)
        setBody(repo)
    }
}

Configuration des timeouts et en-têtes

HttpTimeout et DefaultRequest sont deux plugins clés pour la configuration. HttpTimeout définit les limites de temps, et DefaultRequest spécifie les en-têtes et paramètres d'URL pour toutes les requêtes, éliminant la duplication de code dans chaque appel.

val client = HttpClient {
    install(HttpTimeout) {
        connectTimeoutMillis = 15000
        requestTimeoutMillis = 30000
    }
    install(DefaultRequest) {
        url("https://api.github.com/")
        header("Accept", "application/json")
    }
}

Prise en charge multiplateforme de Ktor

Le multiplateforme est le principal avantage de Ktor par rapport à OkHttp et Retrofit. Ktor Client fonctionne sur JVM (Android, Serveur), Native (iOS, macOS, Windows, Linux) et JS (Navigateur). Le même code client HTTP s'exécute sur toutes les plateformes sans modification, ce qui est particulièrement précieux pour les projets Kotlin Multiplatform.

Pour chaque plateforme, Ktor utilise son propre moteur. Sur Android, le moteur OkHttp est utilisé par défaut, offrant une compatibilité totale avec l'écosystème OkHttp. Sur iOS, DarwinEngine est utilisé, basé sur URLSession. Pour Serveur — CIOEngine (Coroutine I/O). Le moteur peut être spécifié explicitement : HttpClient(OkHttp) { } ou HttpClient(Darwin) { }.

Lors du choix d'un moteur, tenez compte de ses capacités : le moteur OkHttp prend en charge HTTP/2 et le pooling de connexions, DarwinEngine offre une intégration réseau iOS native et des sessions URLSession en arrière-plan, CIOEngine est une implémentation pure de coroutines sans dépendances externes. Pour les cibles Web, JsEngine ou BrowserEngine est utilisé, fonctionnant via fetch API.

Grâce à une API unifiée sur toutes les plateformes, le code de chargement des données est identique sur Android, iOS et Desktop. Cela réduit la duplication de code de 60 à 80% dans les projets KMM par rapport aux implémentations séparées sur Retrofit (Android) et URLSession (iOS). Les plugins fonctionnent également sur toutes les plateformes sans modification.

Erreurs courantes lors de l'utilisation de Ktor

Ignorer la fermeture d'HttpClient est une erreur fréquente dans Ktor. HttpClient implémente Closeable, et il doit être fermé à la fin de l'application via client.close(). Sur Android, cela se fait dans onDestroy() de l'Activity ou ViewModel.onCleared(). Un client non fermé entraîne des fuites de coroutines et de threads du moteur.

Un ordre incorrect des plugins peut casser le traitement des requêtes. Par exemple, ContentNegotiation doit être installé avant DefaultRequest pour que le type de contenu soit appliqué correctement. Il est recommandé d'installer Logging en dernier pour journaliser la version finale de la requête après toutes les modifications. Expérimentez l'ordre si les plugins se comportent de manière inattendue.

Absence de gestion des exceptions dans les fonctions suspend. Ktor lève IOException pour les erreurs réseau et ClientRequestException pour les statuts HTTP 4xx. Le bloc try-catch est obligatoire pour chaque appel à get(), post() et autres méthodes. Utilisez HttpResponseValidator dans le bloc HttpClient pour une gestion globale des erreurs sans dupliquer try-catch dans chaque méthode.