Retrofit para Java: Cliente HTTP Type-safe para Android e Java

1. O que é e para que serve

Retrofit é uma biblioteca poderosa e elegante para Java (e Android) que transforma APIs HTTP em interfaces Java. Em vez de escrever manualmente código repetitivo para criar requisições HTTP, processar respostas e fazer parsing de JSON, o Retrofit faz todo esse trabalho para você. Ele serializa automaticamente seus objetos Java em JSON (ou outro formato) para enviar ao servidor e desserializa as respostas do servidor de volta para objetos Java. Isso torna o código limpo, legível e fácil de manter.

Para que serve? Imagine que você precisa criar um aplicativo que se comunica com uma API REST (como GitHub API, OpenWeatherMap ou seu próprio servidor). Sem o Retrofit, você teria que usar classes de baixo nível como HttpURLConnection ou HttpClient, montar URLs manualmente, configurar cabeçalhos, tratar códigos de erro e fazer parsing de JSON. Isso não é apenas tedioso, mas também propenso a erros. O Retrofit resolve esses problemas fornecendo uma forma declarativa de descrever APIs. Você simplesmente cria uma interface com métodos, os anota (por exemplo, @GET, @POST), e o Retrofit gera automaticamente a implementação dessa interface.

O Retrofit é o padrão de facto para trabalhar com HTTP no mundo Android e Java. Ele se integra perfeitamente com OkHttp (para comunicação de rede eficiente) e Gson/Moshi (para serialização JSON). A biblioteca suporta requisições síncronas e assíncronas, upload de arquivos, autenticação, cache e muitos outros recursos. Graças à sua simplicidade e flexibilidade, o Retrofit é usado em milhares de aplicativos e serviços ao redor do mundo.

2. Instalação

O Retrofit é distribuído através do Maven Central. Para usá-lo em seu projeto Java (com Maven ou Gradle, por exemplo), adicione as dependências correspondentes. Observe que você também precisará de um conversor para serialização (geralmente Gson ou Moshi) e do próprio OkHttp (que o Retrofit usa internamente).

Maven (pom.xml)

<!-- Retrofit -->
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.9.0</version>
</dependency>

<!-- Conversor Gson (para JSON) -->
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.9.0</version>
</dependency>

<!-- OkHttp (geralmente baixado automaticamente, mas você pode especificar a versão) -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

Gradle (build.gradle)

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

Importante: As versões podem ficar desatualizadas. Sempre verifique as versões mais recentes no site oficial ou no repositório Maven Central. Se você usar outro conversor (como Moshi ou Jackson), substitua converter-gson pelo artefato correspondente (converter-moshi, converter-jackson).

3. Início rápido — exemplo funcional mínimo

Vamos escrever um exemplo simples que obtém uma lista de usuários do servidor JSONPlaceholder (uma API REST de teste).

Passo 1: Crie o modelo de dados (POJO)

// User.java
public class User {
    private int id;
    private String name;
    private String username;
    private String email;

    // Getters (obrigatórios para o Gson)
    public int getId() { return id; }
    public String getName() { return name; }
    public