Alamofire — o que é, cliente HTTP em Swift e como funciona

O que é Alamofire?

Alamofire é um cliente HTTP para Swift criado pela Alamofire Software Foundation (originalmente por Mattt Thompson em 2014). A biblioteca abstrai detalhes de baixo nível do URLSession, fornecendo uma API limpa e expressiva para comunicação em rede.

A filosofia central do Alamofire é a sintaxe de encadeamento, onde os parâmetros da requisição (URL, método, cabeçalhos, parâmetros, codificador) são passados através de chamadas sequenciais. Isso torna o código mais legível e reduz a probabilidade de erros relacionados à configuração incorreta do URLRequest. A abordagem declarativa permite focar no que precisa ser feito, em vez dos detalhes de como configurar a conexão. O desenvolvedor descreve o resultado desejado e a biblioteca cuida do trabalho de rede de baixo nível.

A biblioteca é mantida ativamente desde 2014 e passou por sete versões principais. O Alamofire 5, atual em 2025–2026, inclui suporte para Combine, async/await, conversores de resposta, EventMonitor para depuração e RequestInterceptor para interceptar requisições. Cada versão principal trouxe melhorias significativas: o Alamofire 4 adicionou suporte a Codable, o Alamofire 5 adicionou Combine Publishers e um sistema de interceptação de requisições aprimorado.

O ecossistema do Alamofire inclui bibliotecas adicionais: AlamofireImage para carregamento e cache de imagens, AlamofireNetworkActivityIndicator para o indicador de rede na barra de status do iOS e AlamofireObjectMapper para integração com ObjectMapper. Esses componentes fazem do Alamofire uma pilha de rede completa, não apenas um cliente HTTP.

Instalação e configuração

O Alamofire é instalado via Swift Package Manager (recomendado), CocoaPods ou Carthage. No Xcode, basta abrir o menu File → Add Packages, colar o URL do repositório e especificar a versão.

// Swift Package Manager — adicionar ao Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Importar no arquivo
import Alamofire

Após a instalação, o Alamofire fica disponível globalmente através do namespace AF(abreviação de Alamofire) sem configuração adicional. A maioria dos projetos começa configurando uma Session com sua própria configuração — isso permite definir um URL base, cabeçalhos padrão, timeouts e manipuladores de certificados TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

Criar uma sessão personalizada através de Session(configuration:) é necessário quando uma configuração única é necessária para diferentes partes da aplicação — por exemplo, uma sessão separada para downloads de imagens com cache agressivo e outra para requisições de API com autenticação. A Session do Alamofire aceita não apenas configuração, mas também um interceptor, serverTrustManager, cachedResponseHandler e redirectHandler, fornecendo controle total sobre o comportamento da rede em todos os estágios da requisição.

Principais funcionalidades

O Alamofire fornece uma ampla gama de funções que cobrem a maioria dos cenários de interação de rede em aplicações iOS. Vamos ver as principais.

Requisições HTTP

A sintaxe básica de uma requisição inclui o método, URL, parâmetros e codificação. Todos os métodos HTTP padrão são suportados através do enum HTTPMethod: get, post, put, patch, delete. Os parâmetros podem ser codificados como parâmetros de URL (URLEncoding), corpo JSON (JSONEncoding) ou dados multiparte (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("Criado pelo usuário: \(user)")
        case .failure(let error):
            print("Erro: \(error)")
        }
    }

O método validate() verifica automaticamente o código de status (200–299) e o tipo de conteúdo, retornando um erro em caso de resposta inesperada, eliminando a verificação manual de statusCode. O responseDecodable usa o protocolo Decodable para desserialização automática de JSON em estruturas Swift — isso elimina o JSONSerialization manual e reduz o código boilerplate ao trabalhar com APIs REST.

Manipulação de respostas

O Alamofire suporta vários tipos de manipuladores de resposta: response (dados brutos), responseJSON (dicionário/array), responseString (texto), responseData (Data) e responseDecodable (modelo Decodable). Os conversores de resposta podem ser personalizados — para protobuf, formatos gráficos ou protocolos próprios.

Upload e download de arquivos

Para enviar dados ao servidor, usa-se upload, que suporta Data, File e MultipartFormData. O download de arquivos grandes é feito através de download com a capacidade de retomar via resumeData após interrupção da conexão. Ambas as operações suportam rastreamento de progresso através de uploadProgress e downloadProgress com valores fracionários de 0 a 1 para exibição na interface do usuário.

O upload multiparte com Alamofire é particularmente conveniente: o método upload(multipartFormData:) aceita um closure onde as partes do formulário são adicionadas via append. Cada parte pode conter dados, um arquivo ou um fluxo, bem como seu próprio nome e tipo mime. O Alamofire calcula automaticamente os limites multiparte e define o cabeçalho Content-Type correto, poupando o desenvolvedor de formar manualmente o corpo da requisição. Para arquivos grandes, recomenda-se usar provedores de fluxo em vez de carregar o arquivo inteiro na memória — isso evita exceder o limite de memória em dispositivos móveis com recursos limitados. Um cenário típico é enviar o avatar do usuário junto com os dados do perfil em uma única requisição multiparte, reduzindo o número de chamadas HTTP e simplificando o processamento no servidor.

Alamofire vs URLSession

Comparar o Alamofire com o URLSession nativo ajuda a tomar decisões arquiteturais. O Alamofire não substitui o URLSession — ele é construído sobre ele e usa os mesmos mecanismos de configuração, cache e tarefas em segundo plano. Todos os recursos do URLSession são acessíveis através do Alamofire, mas com uma sintaxe declarativa mais conveniente.

Em projetos grandes, o Alamofire reduz o código de requisições de rede em 30–50% e simplifica o tratamento de erros. Em projetos pequenos ou quando o tamanho do binário é uma restrição rigorosa, o URLSession nativo é preferível devido à ausência de dependências externas.

O Alamofire 5 moderno se integra com Combine através da propriedade publishDecodable, que retorna um Publisher, permitindo cadeias de requisições reativas com tratamento de erros e transformação de dados. Para async/await, os métodos com o sufixo value estão disponíveis — por exemplo, AF.request(url).serializingDecodable(User.self).value, tornando a sintaxe extremamente concisa e reminiscente do trabalho com URLSession nativo. Ao usar async/await, os closures não são mais necessários e o tratamento de erros é feito através de blocos do-catch padrão do Swift, simplificando a manutenção e legibilidade do código a longo prazo.

Exemplos de código

Vamos ver um exemplo mais complexo — uma requisição com um interceptador que adiciona automaticamente um token de autorização e realiza uma nova tentativa em caso de erro 401. Este é um cenário típico para aplicações com autenticação JWT.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

O AuthInterceptor implementa dois protocolos: adapt (adiciona um token a cada requisição) e retry (tenta renovar o token em caso de erro 401). O método retry verifica o código de status da resposta e, se um 401 for recebido, solicita um novo token através do TokenManager. Após uma renovação bem-sucedida, a requisição é repetida automaticamente.

Usando o interceptador com uma sessão:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

Todas as requisições através desta sessão passam automaticamente pelo AuthInterceptor — o token é adicionado aos cabeçalhos e, em caso de 401, uma renovação e repetição são realizadas. Isso elimina a duplicação de código de autenticação em cada requisição e centraliza a lógica de gerenciamento de tokens.