OkHttp — o que é, funcionalidades e arquitetura do cliente HTTP

O que é OkHttp?

OkHttp é um cliente HTTP eficiente para Java, Android e Kotlin, desenvolvido pela Square. A biblioteca fornece uma API de baixo nível para executar requisições HTTP com suporte a HTTP/2, SPDY, WebSocket e recuperação automática de conexão em falhas de rede.

OkHttp surgiu em 2013 como resposta à necessidade de um cliente HTTP confiável que resolvesse os problemas do HttpURLConnection — falta de pool de conexões, suporte fraco a HTTP/2 e API inconveniente. Em 2025, o OkHttp é usado em nível de sistema no Android API: o OkHttp está integrado na implementação do HttpURLConnection desde o Android 4.4 (API 19).

De acordo com o Google I/O 2024, o OkHttp processa mais de 70% de todas as requisições HTTP no ecossistema Android. Isso é possível porque o OkHttp atua como camada de transporte para Retrofit, Apollo GraphQL, Firebase e muitas outras bibliotecas. Os desenvolvedores obtêm a funcionalidade do OkHttp automaticamente sem precisar adicioná-lo explicitamente.

Como o OkHttp funciona

Arquitetura do OkHttp é baseada em uma cadeia de interceptadores. Cada requisição passa por uma sequência de interceptadores que podem modificar a Request, a Response ou interromper a execução. Essa arquitetura se assemelha ao padrão Chain of Responsibility e permite extensibilidade flexível.

Quando um aplicativo envia uma requisição, o OkHttp executa as seguintes etapas: resolve DNS, seleciona uma conexão do pool (ou cria uma nova), abre um handshake TLS (se for HTTPS), envia a requisição HTTP, recebe a resposta e a retorna ao aplicativo. RealCall é a classe interna que gerencia o ciclo de vida completo de uma requisição, desde a criação até a conclusão.

O OkHttp lida automaticamente com redirecionamentos (302, 301), tenta novamente requisições em falhas de rede, segue o protocolo keep-alive e suporta compressão gzip transparente. O desenvolvedor não precisa escrever código para essas operações — o OkHttp as faz automaticamente com base nos cabeçalhos do servidor.

Suporte a HTTP/2 e multiplexação

HTTP/2 permite enviar múltiplas requisições em uma única conexão TCP simultaneamente, sem bloqueio head-of-line (característico do HTTP/1.1). O OkHttp usa automaticamente HTTP/2 se o servidor suportar, e volta de forma transparente para HTTP/1.1 quando necessário.

A multiplexação HTTP/2 é especialmente importante para aplicativos móveis, onde a latência de estabelecimento de conexão (TCP + TLS) pode ser de 100–300 ms. Em vez de 10 conexões sequenciais, o OkHttp usa uma, reduzindo a latência total em 40–60% em dispositivos Android típicos com conexões instáveis.

Interceptadores OkHttp: Interceptor e NetworkInterceptor

Interceptor é uma interface com um único método intercept(Chain), que recebe uma Request, executa ações e retorna uma Response. Existem dois tipos de interceptadores: interceptadores de aplicação (adicionados via addInterceptor) e interceptadores de rede (addNetworkInterceptor).

Os interceptadores de aplicação são acionados antes da formação da requisição HTTP — eles veem a Request original e a Response final após todas as transformações. Os interceptadores de rede são acionados no nível da rede: eles veem a requisição após compressão gzip, adição de cabeçalho Content-Length, redirecionamentos e tentativas. Os interceptadores de rede não são chamados se a resposta for servida do cache.

Uso prático dos interceptadores

Na prática, os interceptadores do OkHttp resolvem três tarefas principais: autorização (adicionar o cabeçalho Authorization), registro (HttpLoggingInterceptor para depuração) e repetição (tentativa automática de requisição em falhas de rede). Combinando vários interceptadores, é possível construir um pipeline completo de processamento de requisições sem duplicar código em cada chamada HTTP do aplicativo.

A ordem de adição dos interceptadores importa: o Interceptor adicionado primeiro executa primeiro na entrada e último na saída. Para NetworkInterceptor, a ordem é determinada pela pilha de rede. Ordem recomendada: AuthInterceptor (adiciona token), LoggingInterceptor (registra a requisição), RetryInterceptor (tenta novamente em falhas).

Registro via HttpLoggingInterceptor

Para depurar requisições de rede, usa-se HttpLoggingInterceptor — um interceptador pronto da Square. Ele registra o método, URL, cabeçalhos e corpo da requisição e resposta. Níveis de registro: BASIC (método + URL + código), HEADERS (com cabeçalhos) e BODY (requisição e resposta completos). BODY é útil durante o desenvolvimento, mas é desativado em produção por questões de segurança e desempenho.

Exemplos de código OkHttp em Kotlin

Vamos ver uma requisição GET básica usando OkHttp. Primeiro, um OkHttpClient é criado — um objeto pesado que é criado uma vez e reutilizado. Em seguida, uma Request é formada com uma URL, e a requisição é executada de forma síncrona via execute ou assíncrona via enqueue.

val client = OkHttpClient.Builder()
    .connectTimeout(15, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .build()

val request = Request.Builder()
    .url("https://api.github.com/users/octocat")
    .header("Accept", "application/vnd.github.v3+json")
    .build()

val response = client.newCall(request).execute()
println(response.body()?.string())

Para a execução assíncrona, usa-se o método enqueue, que aceita um Callback. O OkHttp executa a requisição em uma thread em segundo plano e retorna o resultado no callback na mesma thread. Para alternar para a thread principal do Android, use Handler ou corrotinas.

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(
        call: Call, e: IOException
    ) {
        println("Falha na solicitação: ${e.message}")
    }

    override fun onResponse(
        call: Call, response: Response
    ) {
        println(response.body()?.string())
    }
})

Adicionar um interceptador para autorização

Um Interceptor personalizado adiciona um token Bearer a cada requisição. O interceptador verifica a presença do cabeçalho Authorization e, se o token ainda não estiver definido, adiciona-o do armazenamento. Em uma resposta 401, o interceptador pode atualizar o token via Authenticator.

class AuthInterceptor(
    private val tokenProvider: () -> String?
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val originalRequest = chain.request()
        val token = tokenProvider.invoke()
        val request = originalRequest.newBuilder()
            .header("Authorization", "Bearer $token")
            .build()
        return chain.proceed(request)
    }
}

Pool de conexões e cache no OkHttp

Pool de conexões (ConnectionPool) é uma otimização chave do OkHttp que permite reutilizar conexões TCP para múltiplas requisições. Em vez de criar um novo socket para cada requisição, o OkHttp armazena até 5 conexões inativas (por padrão) por 5 minutos, reduzindo a latência em 30–70% para requisições repetidas ao mesmo host.

O cache de respostas é implementado através da classe Cache. Para ativar o cache, basta especificar o diretório e o tamanho máximo no OkHttpClient.Builder. O OkHttp armazena em cache automaticamente as respostas GET de acordo com os cabeçalhos Cache-Control, Expires e ETag, retornando dados em cache sem requisição de rede se não estiverem desatualizados.

val cacheDir = File(context.cacheDir, "http-cache")
val cache = Cache(cacheDir, 10L * 1024 * 1024)

val client = OkHttpClient.Builder()
    .cache(cache)
    .connectionPool(ConnectionPool(5, 5, TimeUnit.MINUTES))
    .build()

A configuração adequada do pool e do cache é especialmente importante para aplicativos com requisições frequentes — feeds de notícias, chats, atualizações de dados. Sem pool, cada conexão TCP exige um handshake de três vias (SYN, SYN-ACK, ACK) e potencialmente um handshake TLS (2–3 viagens de ida e volta), adicionando 100–500 ms a cada requisição.

O OkHttp também suporta WebSocket através da classe RealWebSocket. Uma conexão WebSocket é estabelecida através de um handshake HTTP (101 Switching Protocols) e depois muda para um protocolo bidirecional. O OkHttp envia automaticamente quadros ping para manter a conexão ativa e reconecta em caso de desconexão. O WebSocket do OkHttp é compatível com endpoints padrão como wss://echo.websocket.org.

Erros comuns ao trabalhar com OkHttp

Criar OkHttpClient para cada requisição é o erro mais comum. OkHttpClient contém um pool de conexões, cache e pool de threads. Criar uma nova instância para cada requisição não só desperdiça memória, mas também perde o benefício da reutilização de conexões. OkHttpClient deve ser um singleton através de um contêiner DI.

Ignorar o fechamento de Response.body() causa vazamento de recursos. ResponseBody contém um InputStream que deve ser fechado após a leitura. Se usar body().string() ou body().bytes(), o OkHttp fecha o fluxo automaticamente, mas ao ler body().byteStream() ou body().charStream(), é necessária uma chamada explícita close() em um bloco finally.

Falta de tratamento de Timeout é outro problema. Por padrão, o OkHttp tem connectTimeout de 10 segundos, readTimeout de 10 segundos e writeTimeout de 10 segundos. Para aplicativos móveis com conexões instáveis, é recomendado definir connectTimeout de 15–30 segundos e readTimeout de 15–30 segundos, caso contrário o usuário esperará muito tempo com sinal fraco.