Alamofire: o que é, funções do cliente HTTP e uso no desenvolvimento

O que é Alamofire?

Alamofire é uma biblioteca para trabalhar com requisições HTTP em plataformas Apple, escrita inteiramente em Swift. O desenvolvimento começou em 2014 como uma alternativa à biblioteca AFNetworking em Objective-C e rapidamente se tornou o padrão para comunicação em rede na comunidade iOS.

A biblioteca é construída sobre o framework do sistema URLSession, abstraindo sua API de baixo nível em cadeias de métodos concisas. Alamofire suporta todos os recursos do URLSession: sessões em segundo plano, interceptores de requisições, certificados SSL e múltiplos métodos de serialização de respostas.

De acordo com o Swift Package Index, Alamofire está entre os 10 pacotes Swift mais populares com mais de 45.000 estrelas no GitHub. A biblioteca é compatível com iOS 10+, macOS 10.12+, tvOS 10+ e watchOS 3+.

A principal vantagem do Alamofire sobre o uso direto do URLSession é a redução de código boilerplate. Uma única chamada AF.request substitui 15–20 linhas de configuração manual de URLRequest, tratamento de resposta e decodificação de dados. Ao mesmo tempo, a biblioteca mantém total flexibilidade para cenários personalizados através de sessões e extensões personalizadas.

Principais recursos do Alamofire

Alamofire fornece uma ampla gama de funções de rede que cobrem a maioria dos cenários de desenvolvimento móvel. Graças à sua arquitetura modular, os desenvolvedores só precisam incluir os componentes necessários.

Suporte para todos os métodos HTTP

Os métodos HTTP GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS e TRACE são implementados através de uma API uniforme. Cada método aceita parâmetros de requisição, cabeçalhos e retorna uma resposta como tipo Result. O desenvolvedor não precisa configurar URLRequest manualmente — a biblioteca faz isso automaticamente com base nos argumentos fornecidos.

Validação de respostas do servidor

A validação de respostas no Alamofire permite verificar códigos de status e conteúdo da resposta antes de passar os dados para a aplicação. A biblioteca suporta condições de validação personalizadas através de closures, dando controle total sobre o tratamento de erros. Por padrão, apenas os códigos de status 200–299 são verificados.

Codificação automática de parâmetros

Os parâmetros são codificados automaticamente dependendo do tipo selecionado: codificação URL para requisições GET e codificação JSON para POST. Alamofire também suporta codificação Property List e codificadores personalizados através do protocolo ParameterEncoder, permitindo adaptar o formato para qualquer servidor.

Gerenciamento de sessão e interceptores

A sessão no Alamofire permite configurar timeouts, certificados SSL, cabeçalhos HTTP padrão e proxies. Os interceptores EventMonitor permitem rastrear eventos do ciclo de vida da requisição: criação, envio, recebimento de resposta e conclusão. Isso é útil para logging, análise e depuração de problemas de rede em produção.

Como o Alamofire funciona?

Alamofire usa uma arquitetura baseada em Session que encapsula uma instância do URLSession e a configuração de rede. Cada requisição passa por uma cadeia de handlers: adaptadores, políticas de repetição, validadores e serializadores, garantindo flexibilidade e extensibilidade.

Modelo de Session e Request

O objeto Session gerencia todas as requisições de rede na aplicação. Ele é criado com uma configuração contendo timeouts, cabeçalhos padrão e certificados. Cada chamada AF.request retorna um DataRequest que pode ser modificado antes do envio. Alamofire trata automaticamente ciclos de retenção através de referências fracas para a sessão, prevenindo vazamentos de memória.

import Alamofire

let session = Session(configuration: config)
session.request("https://api.example.com/users")
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("Recebidos \(users.count) usuários")
        case .failure(let error):
            print("Erro: \(error.localizedDescription)")
        }
    }

Instalação e configuração do Alamofire

A instalação do Alamofire é feita através do Swift Package Manager, CocoaPods ou Carthage. O método recomendado para novos projetos é o SPM, integrado ao Xcode, pois não requer ferramentas adicionais e a integração é feita em poucos cliques.

Através do Swift Package Manager

Adicionar o pacote no Xcode é feito através do menu File → Add Packages. URL do repositório: https://github.com/Alamofire/Alamofire. Recomenda-se fixar a versão no último lançamento estável. Alamofire segue versionamento semântico e todas as mudanças significativas são documentadas no CHANGELOG.

Através do CocoaPods

CocoaPods continua sendo uma opção popular para projetos com infraestrutura existente. Adicione a linha pod 'Alamofire' ao seu Podfile e execute pod install. Alamofire não tem dependências externas, o que simplifica a integração e elimina conflitos de versão em projetos existentes.

Exemplos de uso do Alamofire

Os exemplos abaixo demonstram cenários típicos de uso do Alamofire em aplicações iOS: desde requisições GET simples até upload de arquivos com acompanhamento de progresso.

Requisição GET e resposta JSON

Uma requisição GET simples com parâmetros e decodificação da resposta em um modelo Codable é o cenário mais comum de uso do Alamofire em aplicações móveis. Os parâmetros são codificados automaticamente e a resposta é decodificada através do JSONDecoder. O código é compacto e legível.

struct User: Codable {
    let id: Int
    let name: String
    let email: String
}

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .get)
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("Usuários: \(users.count)")
        case .failure(let error):
            print("Erro: \(error)")
        }
    }

Requisição POST com corpo JSON

Uma requisição POST com corpo JSON é usada para criar recursos no servidor. Alamofire codifica automaticamente o objeto passado através do JSONParameterEncoder, poupando o desenvolvedor da serialização manual. A resposta é decodificada em um modelo de dados usando o mesmo JSONDecoder.

let newUser = User(id: 1,
                     name: "João Silva",
                     email: "ivan@example.com")

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .post,
               parameters: newUser,
               encoder: JSONParameterEncoder.default)
    .validate()
    .responseDecodable(of: User.self) { response in
        if let created = response.value {
            print("Usuário criado: \(created)")
        }
    }

Upload de mídia

O método upload no Alamofire suporta upload de arquivos, dados e formulários multipart. A biblioteca gerencia automaticamente o progresso e permite acompanhar o status do upload através de closures uploadProgress, o que é conveniente para exibir um indicador de progresso.

let imageData = UIImage(named: "photo")?.jpegData(compressionQuality: 0.8)

AF.upload(imageData,
           to: "https://api.example.com/upload")
    .uploadProgress { progress in
        print("Progresso: \(progress.fractionCompleted * 100)%")
    }
    .responseDecodable(of: UploadResponse.self) { response in
        print("Upload concluído")
    }

Tratamento de erros e validação no Alamofire

O tratamento de erros no Alamofire é baseado em uma combinação de validação de respostas e tipos Result. O modelo de erros inclui AFError, que cobre todos os cenários típicos de falha de rede: timeouts, perda de conexão, erros de servidor e serialização falha. Cada caso é tratado separadamente.

Para tentativas repetidas após um erro, Alamofire fornece o mecanismo RequestRetrier. Este protocolo define a política de repetição: número de tentativas, intervalo entre elas e a condição sob a qual uma repetição é realizada. Por exemplo, em um erro 503 do servidor, a requisição pode ser repetida após 2 segundos, enquanto em um erro 401, um novo token de autenticação pode ser solicitado.

A abordagem de enumeração AFError garante que o desenvolvedor não perca nenhum tipo de erro — o compilador verifica a completude do tratamento. Isso torna o código mais confiável e previsível em comparação com o tratamento de erros via NSError no URLSession puro.

Políticas de repetição e requisições repetidas

O protocolo RequestRetrier define um método de repetição que recebe a requisição, a sessão, o erro e o closure de conclusão. Neste método, o desenvolvedor decide se deve repetir a requisição e após quanto tempo. Alamofire fornece uma implementação embutida RetryPolicy para cenários comuns, mas para código de produção recomenda-se criar políticas personalizadas baseadas na lógica de negócio.

AFError é uma enumeração com casos aninhados para diferentes categorias de erros. O desenvolvedor pode tratar cada tipo separadamente: para timeouts — repetir a requisição, para erros de servidor — mostrar uma mensagem compreensível ao usuário. Alamofire suporta políticas de repetição personalizadas através do protocolo RequestRetrier.

A validação embutida verifica códigos de status na faixa 200–299 e o tipo de conteúdo da resposta. Para validação estendida, condições personalizadas podem ser adicionadas através do closure validate, permitindo verificar a lógica de negócio antes de passar os dados para a camada de UI.