Retrofit — o que é, biblioteca HTTP e uso em aplicações

O que é Retrofit?

Retrofit é uma biblioteca para fazer requisições HTTP em aplicações Android, desenvolvida pela Square. Ela fornece uma abordagem declarativa para definir APIs REST através de interfaces Java com anotações, tornando o código de interação de rede limpo e previsível.

A ideia central do Retrofit é que o desenvolvedor descreve a API como uma interface com métodos e anotações, e a biblioteca gera a implementação automaticamente. Esta abordagem garante que todos os endpoints sejam tipados, e erros em URLs ou parâmetros sejam detectados em tempo de compilação, não em tempo de execução.

O Retrofit suporta todos os métodos HTTP populares e formatos de dados. A biblioteca é ativamente mantida pela Square e pela comunidade: novas versões são lançadas regularmente, e a versão atual 2.11 inclui suporte para Java 17 e Kotlin 2.0. O Retrofit continua sendo o cliente HTTP mais popular para Android.

O Retrofit funciona sobre o OkHttp, um cliente HTTP eficiente também da Square. Esta combinação fornece cache, interceptação de requisições e gerenciamento de conexões ao nível do protocolo de transporte. A biblioteca suporta chamadas síncronas e assíncronas.

Desde seu primeiro lançamento em 2013, o Retrofit passou por várias atualizações importantes. A versão atual Retrofit 2 foi completamente reescrita com base na experiência da primeira versão e oferece um sistema mais flexível de conversores e adaptadores para assincronia.

A arquitetura do Retrofit segue o princípio de separação de responsabilidades: a interface define apenas o contrato da API, os conversores lidam com a serialização e os adaptadores gerenciam a assincronia. Isto permite substituir qualquer componente sem alterar o resto do código. Por exemplo, você pode mudar de Gson para Moshi sem modificar as definições dos endpoints.

Principais funcionalidades do Retrofit

Retrofit fornece um conjunto de funcionalidades que cobrem praticamente todos os cenários de interação de rede em aplicações móveis. A principal vantagem é o estilo declarativo de definição de API.

Anotações declarativas de endpoints

As anotações @GET, @POST, @PUT, @PATCH, @DELETE e @HTTP permitem especificar o método HTTP e o template de URL diretamente na interface. Os parâmetros de caminho são definidos via @Path, os parâmetros de consulta via @Query e o corpo da requisição via @Body. Esta abordagem torna a camada de API da aplicação completamente tipada.

Conversores para serialização

Os conversores transformam respostas HTTP em objetos Java e vice-versa. O Retrofit suporta Gson, Moshi, Jackson, Protobuf e Wire. O desenvolvedor conecta o conversor necessário através de Converter.Factory, e a biblioteca aplica-o automaticamente a todas as requisições e respostas.

Adaptadores para assincronia

Os adaptadores CallAdapter permitem alterar o tipo de retorno dos métodos da API. Em vez do Call padrão, pode-se usar Observable para RxJava, Deferred para corrotinas Kotlin ou LiveData. Isto integra as requisições de rede com a arquitetura de aplicação escolhida.

URLs dinâmicas e cabeçalhos

URLs dinâmicas são definidas através da anotação @Url, permitindo passar o endpoint em tempo de execução. Os cabeçalhos podem ser especificados estaticamente via @Headers ou dinamicamente através do parâmetro @Header. Para cabeçalhos globais em todas as requisições, utiliza-se um interceptador do OkHttp que adiciona cabeçalhos a cada requisição de saída.

Como o Retrofit funciona?

Retrofit funciona em três etapas: definir a interface da API, criar uma instância do Retrofit e executar a requisição. A biblioteca gera a implementação da interface em tempo de execução com base nas anotações e conversores.

Ciclo de vida da requisição

Quando um método da API é chamado, o Retrofit cria um objeto Request com base nas anotações e argumentos. A requisição é passada para o OkHttp para execução. Após receber a resposta, a biblioteca a passa para o Converter.Factory para transformação no tipo necessário. O CallAdapter envolve o resultado num invólucro assíncrono. Cada etapa pode ser personalizada.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

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

Instalação e configuração do Retrofit

A instalação do Retrofit é feita através do Gradle, o sistema de compilação padrão do Android. A biblioteca é distribuída através do Maven Central e requer a adição de várias dependências ao build.gradle do projeto.

Adicionar dependências

No ficheiro build.gradle (ao nível do módulo), adicione dependências para Retrofit, conversor Gson e OkHttp. Recomenda-se extrair as versões das bibliotecas em variáveis no build.gradle raiz para gestão centralizada. O Retrofit 2 requer um mínimo de Android API 21.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Criar uma instância do Retrofit

Uma instância do Retrofit é criada através do Builder. Parâmetros obrigatórios: baseUrl e ConverterFactory. Recomenda-se usar um singleton para Retrofit e OkHttpClient para evitar criar conexões redundantes. Adicionar um logging-interceptor simplifica a depuração de requisições de rede durante o desenvolvimento.

Para projetos Kotlin, recomenda-se usar funções suspend na interface da API em vez de tipos Call. Isto simplifica o código e permite usar a concorrência estruturada das corrotinas. Ao mudar de Call para suspend, basta alterar o tipo de retorno na interface — o resto do código adapta-se automaticamente.

Exemplos de uso do Retrofit

Os exemplos abaixo demonstram cenários típicos de trabalho com Retrofit em aplicações Android: desde uma simples requisição GET até ao upload de um ficheiro para o servidor.

Requisição GET com parâmetros de consulta

Uma requisição GET simples com parâmetros de string de consulta é uma operação básica. A anotação @Query adiciona parâmetros à URL automaticamente, e a função suspend permite chamar a requisição a partir de uma corrotina sem bloquear a thread principal.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

Requisição POST com corpo JSON

Uma requisição POST com corpo JSON usa a anotação @Body para passar o objeto. O GsonConverterFactory serializa automaticamente o objeto User em JSON. As corrotinas Kotlin garantem a execução da requisição na thread de fundo sem interfaces Callback.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Ana Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Upload de ficheiro via Multipart

A anotação @Multipart com @Part permite fazer upload de ficheiros para o servidor. O Retrofit forma automaticamente uma requisição multipart com os cabeçalhos necessários. O OkHttp gere o progresso do upload através do RequestBody, permitindo exibir um indicador ao utilizador.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Tratamento de erros e interceptadores no Retrofit

O tratamento de erros no Retrofit é construído numa combinação de mecanismos do OkHttp e corrotinas Kotlin. Os interceptadores do OkHttp permitem registar requisições, adicionar cabeçalhos de autenticação e tratar erros antes que estes atinjam o código da aplicação.

Para tratamento centralizado de erros, cria-se frequentemente um invólucro em torno das chamadas à API como uma classe selada Result. Essa classe tem duas subclasses: Success com dados e Error com uma exceção. O ViewModel recebe um resultado unificado e pode exibir o estado correspondente da interface do utilizador sem duplicar código de tratamento de erros em cada função.

Os interceptadores são de dois tipos: interceptadores de aplicação modificam a requisição antes de a enviar para o servidor, e interceptadores de rede trabalham com a resposta após a receção. Por exemplo, um interceptador pode renovar automaticamente o token de acesso ao receber um 401 e repetir a requisição com o novo token sem intervenção do desenvolvedor.

Registo de requisições através de Interceptor

O interceptador de registo HttpLoggingInterceptor é uma ferramenta indispensável para depurar requisições de rede. Ele exibe no Logcat o método da requisição, URL, cabeçalhos, corpo e código de resposta. O nível de registo pode ser configurado: BASIC para informação mínima, HEADERS para cabeçalhos ou BODY para conteúdo completo. Em produção, recomenda-se usar BASIC ou desativar o registo completamente.

Os interceptadores no OkHttp dividem-se em dois tipos: interceptadores de aplicação para modificar a requisição e interceptadores de rede para trabalhar com dados de rede brutos. O interceptador de registo exibe automaticamente os detalhes da requisição e resposta no Logcat.

O tratamento de erros ao nível das corrotinas é feito através de try-catch em torno da chamada à função suspend. O Retrofit retorna erros como HttpException para códigos 4xx e 5xx, UnknownHostException quando não há rede e SocketTimeoutException quando o tempo limite é excedido. Recomenda-se usar uma classe selada Result para tratamento unificado.