Retrofit: o que é, características do cliente HTTP Android

O que é Retrofit?

Retrofit é uma biblioteca para interação tipada com REST API na plataforma Android, desenvolvida pela Square. Ela fornece uma maneira declarativa de descrever requisições HTTP através de interfaces Java ou Kotlin com anotações, eliminando completamente a necessidade de parsing manual de JSON e gerenciamento de conexões HTTP.

A biblioteca surgiu em 2013 como alternativa a soluções complicadas como AsyncTask e HttpURLConnection. Em 2025, o Retrofit continua sendo o padrão de facto para comunicação de rede em aplicativos Android graças à sua simplicidade e segurança de tipos. De acordo com a pesquisa JetBrains Developer Ecosystem 2024, mais de 65% dos desenvolvedores Android usam Retrofit em projetos comerciais.

A principal diferença do Retrofit em relação às alternativas é a abordagem declarativa: o desenvolvedor descreve o que fazer (qual endpoint chamar, quais parâmetros passar) em vez de como fazer (como abrir uma conexão, como ler um InputStream, como analisar JSON). Isso reduz o código boilerplate em 60–70% em comparação com o uso manual de HttpURLConnection.

Como o Retrofit funciona

O princípio de funcionamento do Retrofit é baseado em proxies dinâmicos Java. Quando o desenvolvedor chama um método de uma interface anotada, o Retrofit intercepta a chamada através do mecanismo Proxy.newProxyInstance e a converte em uma requisição HTTP. Todo o processo ocorre em tempo de execução sem geração de código em tempo de compilação.

Ao criar uma instância do Retrofit.Builder, a URL base e a fábrica de conversores são especificadas. O Builder configura o OkHttpClient — define timeouts, interceptadores, pool de conexões e cache. O método create(Class) gera a implementação da interface, retornando um objeto proxy que pode ser chamado como uma classe comum.

A cadeia de execução da requisição é assim: as anotações extraem o método HTTP, os parâmetros são substituídos na URL ou corpo da requisição, o conversor serializa o corpo, o OkHttp executa a requisição, o conversor desserializa a resposta e o resultado é retornado no tipo especificado. Cada etapa é isolada e pode ser substituída por uma implementação personalizada, por exemplo substituir OkHttpClient por MockWebServer para testes ou trocar o conversor ao mudar a API.

Uma característica importante — o Retrofit não suporta transmissão de dados em streaming diretamente. Para streaming, usa-se OkHttp ResponseBody como tipo de retorno do método da interface. O Retrofit também não gerencia o cancelamento de requisições automaticamente — para cancelar é necessário manter uma referência ao Call e chamar cancel(). Em Kotlin com funções suspend, o cancelamento da requisição ocorre automaticamente ao cancelar a corrotina pai.

Ciclo de vida do objeto Call

Call<T> é um objeto que representa uma única requisição HTTP. Após a execução (execute ou enqueue), um Call não pode ser reutilizado — para uma nova requisição é preciso criar um novo Call chamando o método da interface. Isso evita o envio acidental da mesma requisição duas vezes, o que poderia causar operações duplicadas no servidor.

Em Kotlin, em vez de Call, são usadas funções suspend, que gerenciam automaticamente o ciclo de vida da requisição. O Retrofit alterna a execução para Dispatchers.IO e retorna o resultado para a corrotina. Isso reduz o código em 30–40% em comparação com a versão com Call e Callback.

Anotações do Retrofit para métodos HTTP

As anotações são o mecanismo principal de configuração de requisições HTTP no Retrofit. Cada anotação corresponde a um método HTTP padrão e aceita um caminho relativo ao endpoint. O Retrofit suporta GET, POST, PUT, DELETE, PATCH, HEAD e OPTIONS.

Anotações de parâmetros de requisição

@Path substitui um valor em um segmento de URL: @Path("id") Int id substitui {id} no caminho. @Query adiciona um parâmetro de consulta: @Query("page") Int page se transforma em ?page=5. @Body passa um objeto no corpo da requisição com serialização automática através do conversor selecionado. @Header e @Headers gerenciam cabeçalhos HTTP — estáticos ou dinâmicos.

Combinando essas anotações, é possível descrever qualquer endpoint REST. Por exemplo, para o endpoint POST /api/users/{id}/posts?limit=10 são necessários @POST, @Path para id, @Query para limit e @Body para o objeto passado. O Retrofit montará automaticamente uma requisição HTTP correta. Adicionalmente, são suportados @Url (URL dinâmica), @Field (corpo codificado em formulário), @Part e @PartMap para requisições multipart com arquivos.

Exemplos de código Retrofit em Kotlin

Vamos ver um exemplo prático — uma interface para a API do GitHub. Uma interface Kotlin é criada com um método para obter a lista de repositórios. A classe de dados Repo descreve a estrutura da resposta JSON.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Após descrever a interface, uma instância do Retrofit é criada através do Builder. A URL base, o conversor e o OkHttpClient são configurados uma vez e reutilizados através de injeção de dependência.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

val api = retrofit.create(GitHubApi::class.java)

Tratamento de resposta com wrapper Response

Para tratamento flexível de códigos de status HTTP, use o wrapper Response<T>. Ele fornece acesso ao código de resposta, cabeçalhos e corpo sem lançar exceções em erros 4xx e 5xx. Isso permite tratar 404 e 500 sem try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Conversores e serialização no Retrofit

Conversores são componentes do Retrofit responsáveis por converter objetos em corpo HTTP e vice-versa. O Retrofit não incorpora serialização em seu núcleo — em vez disso, usa uma abordagem modular através de Converter.Factory, permitindo conectar qualquer biblioteca de serialização.

O conversor mais popular é o GsonConverterFactory do Google baseado na biblioteca Gson. Funciona para a maioria dos projetos, suporta TypeAdapter e JsonDeserializer personalizados. No entanto, o Gson usa reflexão e não respeita a segurança nula do Kotlin, o que pode causar NPE em campos nulos inesperados.

Uma alternativa é o MoshiConverterFactory da Square: mais rigoroso com tipos, com melhor suporte ao Kotlin (segurança nula, valores padrão) e sem reflexão. Para projetos em Kotlin puro, o ideal é o Kotlinx Serialization Converter, que trabalha com anotações @Serializable em tempo de compilação. Ele não usa reflexão, suporta sealed class, valores padrão e multiplataforma.

A escolha do conversor afeta o desempenho e a segurança de tipos. O Gson sem configuração personalizada pode desserializar null em um campo não nulo do Kotlin, causando NPE ao acessar. O Moshi resolve esse problema através da anotação @Json(name) e failOnUnknown. O Kotlinx Serialization é o mais seguro — ele gera código em tempo de compilação, eliminando completamente erros de tipo em tempo de execução.

Erros comuns ao trabalhar com Retrofit

Falta de tratamento de erros HTTP em funções suspend é o problema mais frequente. Se o servidor retornar 4xx ou 5xx, o Retrofit lança HttpException. Sem try-catch, o aplicativo quebra. Usar Response<T> como tipo de retorno resolve isso, permitindo verificar isSuccessful antes de acessar o body.

Configuração incorreta de cache leva a tráfego excessivo. O Retrofit não armazena respostas em cache por conta própria — essa tarefa é feita pelo OkHttpClient através de Cache. Sem cache, cada requisição é executada completamente, mesmo quando os dados não mudaram. Adicionar um Cache de 10 MB no OkHttpClient reduz o tráfego em 40–60% em requisições repetidas da mesma informação.

Criar Retrofit para cada requisição é um erro comum de iniciantes. Retrofit.Builder é uma operação custosa que envolve geração de classes proxy em tempo de execução. A boa prática é criar uma única instância do Retrofit e reutilizá-la através de frameworks de DI. Hilt, Koin ou Dagger fornecem uma instância singleton do Retrofit para todo o aplicativo, economizando memória e acelerando as requisições.

Ignorar Interceptor para autorização é o quarto problema. Em vez de adicionar manualmente o cabeçalho Authorization em cada chamada, configure um Interceptor global no OkHttpClient. O Interceptor intercepta cada requisição, adiciona o token Bearer, e o Authenticator lida com a resposta 401, renovando o token e repetindo a requisição automaticamente. Isso centraliza a lógica de autenticação.