Ktor: o que é, características do cliente HTTP assíncrono

O que é Ktor?

Ktor é um framework para construir aplicações assíncronas de servidor e cliente em Kotlin, criado pela JetBrains. Ktor Client é a parte cliente do framework, fornecendo um cliente HTTP com suporte completo a corrotinas Kotlin, multiplataforma (JVM, Native, JS) e uma arquitetura modular baseada em plugins.

Ktor surgiu em 2018 como alternativa ao Retrofit e OkHttp para projetos Kotlin-first. Ao contrário do Retrofit, que adaptou a abordagem Java com anotações, o Ktor Client usa Kotlin DSL para configuração de requisições — sem anotações ou reflexão. Isso torna o código mais legível e type-safe para desenvolvedores Kotlin.

De acordo com a pesquisa Kotlin Multiplatform 2024, o Ktor Client é usado em 35% dos projetos Kotlin Multiplatform Mobile (KMM), tornando-se o segundo cliente HTTP mais popular depois do OkHttp na comunidade Kotlin. Ktor é preferido em projetos onde o suporte multiplataforma e a integração nativa com o ecossistema Kotlin são importantes.

Como funciona o Ktor Client

A arquitetura do Ktor Client é baseada em um pipeline de plugins. Cada requisição passa por uma sequência de plugins instalados que podem modificar a requisição, a resposta ou executar ações secundárias — registro, compressão, serialização, autenticação.

Ao criar um cliente HTTP através do bloco DSL HttpClient { }, você especifica o mecanismo (OkHttp, Android, CIO, Darwin) e instala os plugins. Cada mecanismo implementa o envio de requisições de baixo nível para uma plataforma específica: no Android usa-se o mecanismo OkHttp, no iOS — Darwin (URLSession), no Desktop — CIO (Coroutine I/O). O HttpClient seleciona automaticamente o mecanismo ideal para a plataforma atual.

Uma requisição no Ktor Client é executada através de uma função suspend, o que significa integração total com corrotinas. Sem Callbacks, sem RxJava ou LiveData — apenas código sequencial com suspend que funciona de forma assíncrona sem bloquear a thread.

Pipeline de processamento de requisições

O pipeline do Ktor consiste em fases: primeiro a requisição passa pelos plugins instalados (ex.: ContentNegotiation para JSON, Logging para registros), então o mecanismo executa a requisição HTTP, e a resposta passa novamente pelos plugins para desserialização. Cada plugin é uma função suspend executando na corrotina do pipeline.

Uma vantagem importante do pipeline do Ktor é a capacidade de realizar processamento condicional. Um plugin pode verificar a URL ou os cabeçalhos da requisição e pular o processamento se a condição não for atendida. Por exemplo, ContentEncoding com gzip é aplicado apenas a respostas contendo o cabeçalho Content-Encoding: gzip, e Auth só é acionado para endpoints protegidos sem afetar APIs públicas.

Essa abordagem de pipeline permite combinar plugins de forma flexível: você pode instalar ContentNegotiation com JSON, adicionar Auth com token Bearer, ativar a compressão ContentEncoding e HttpTimeout — e todos funcionarão juntos na ordem correta. A ordem de instalação dos plugins é importante: o primeiro plugin instalado processará a requisição antes dos demais.

Plugins do Ktor Client

Os plugins são o sistema de extensão modular do Ktor, substituindo as anotações do Retrofit e os interceptadores do OkHttp. Cada plugin resolve uma tarefa específica e é instalado através da função install() no bloco HttpClient. Ktor fornece plugins integrados e também permite criar plugins personalizados.

Plugins personalizados

Para tarefas específicas, um plugin personalizado é criado através de createClientPlugin. O plugin pode interceptar a requisição (onRequest), a resposta (onResponse) ou tratar erros (onError). Isso substitui completamente o Interceptor do OkHttp, mas com uma API Kotlin tipada e suporte a funções suspend.

Plugins personalizados são convenientes para adicionar métricas, lógica de repetição automática, rastreamento de requisições ou testes A/B de endpoints. Ao contrário dos interceptadores do OkHttp, os plugins do Ktor são escritos em Kotlin e executados no contexto da corrotina, simplificando o tratamento de erros e timeouts.

Para depuração de requisições, utiliza-se o plugin Logging com nível ALL, HEADERS ou BODY. O Logging exibe o método, URL, status, cabeçalhos e corpo da requisição e resposta. Ao contrário do HttpLoggingInterceptor do OkHttp, o Ktor Logging funciona de forma assíncrona e pode ser configurado para filtrar por nível de log (ERROR, WARN, INFO, DEBUG) sem parar a aplicação para alterar a configuração.

Exemplos de código do Ktor Client em Kotlin

Vejamos uma requisição GET básica com Ktor Client. Um HttpClient é criado com o plugin ContentNegotiation instalado para JSON. A requisição é executada através da função suspend get(), e o resultado é automaticamente desserializado em uma 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()
}

Para uma requisição POST com corpo, utiliza-se a função post() com contentType() e body(). O Ktor serializa automaticamente o objeto para JSON através do ContentNegotiation instalado. O estilo DSL torna o código sequencial e legível.

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

Configuração de timeouts e cabeçalhos

HttpTimeout e DefaultRequest são dois plugins-chave para configuração. HttpTimeout define limites de tempo, e DefaultRequest especifica cabeçalhos e parâmetros de URL para todas as requisições, eliminando a duplicação de código em cada chamada.

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

Suporte multiplataforma do Ktor

A multiplataforma é a principal vantagem do Ktor sobre OkHttp e Retrofit. O Ktor Client funciona em JVM (Android, Servidor), Native (iOS, macOS, Windows, Linux) e JS (Navegador). O mesmo código de cliente HTTP é executado em todas as plataformas sem alterações, o que é especialmente valioso para projetos Kotlin Multiplatform.

Para cada plataforma, o Ktor usa seu próprio mecanismo. No Android, usa-se por padrão o mecanismo OkHttp, que oferece compatibilidade total com o ecossistema OkHttp. No iOS, usa-se o DarwinEngine, baseado em URLSession. Para Servidor — CIOEngine (Coroutine I/O). O mecanismo pode ser especificado explicitamente: HttpClient(OkHttp) { } ou HttpClient(Darwin) { }.

Ao escolher um mecanismo, considere suas capacidades: o mecanismo OkHttp suporta HTTP/2 e pool de conexões, o DarwinEngine oferece integração nativa de rede iOS e sessões URLSession em segundo plano, o CIOEngine é uma implementação pura de corrotinas sem dependências externas. Para alvos Web, usa-se JsEngine ou BrowserEngine, que funcionam através da fetch API.

Graças a uma API unificada em todas as plataformas, o código para carregar dados parece o mesmo no Android, iOS e Desktop. Isso reduz a duplicação de código em 60–80% em projetos KMM em comparação com implementações separadas em Retrofit (Android) e URLSession (iOS). Os plugins também funcionam em todas as plataformas sem alterações.

Erros comuns ao trabalhar com Ktor

Ignorar o fechamento do HttpClient é um erro comum no Ktor. HttpClient implementa Closeable, e deve ser fechado quando a aplicação terminar via client.close(). No Android, isso é feito no onDestroy() da Activity ou ViewModel.onCleared(). Um cliente não fechado causa vazamentos de corrotinas e threads do mecanismo.

Ordem incorreta dos plugins pode quebrar o processamento de requisições. Por exemplo, ContentNegotiation deve ser instalado antes de DefaultRequest para que o tipo de conteúdo seja aplicado corretamente. Recomenda-se instalar o Logging por último para registrar a versão final da requisição após todas as modificações. Experimente a ordem se os plugins se comportarem inesperadamente.

Falta de tratamento de exceções em funções suspend. Ktor lança IOException para erros de rede e ClientRequestException para status HTTP 4xx. O bloco try-catch é obrigatório para cada chamada a get(), post() e outros métodos. Use HttpResponseValidator no bloco HttpClient para tratamento global de erros sem duplicar try-catch em cada método.