Alamofire — cos'è, client HTTP in Swift e come funziona

Cos'è Alamofire?

Alamofire è un client HTTP per Swift creato da Alamofire Software Foundation (originariamente da Mattt Thompson nel 2014). La libreria astrae i dettagli di basso livello di URLSession, fornendo un'API pulita ed espressiva per la comunicazione di rete.

La filosofia principale di Alamofire è la sintassi a concatenamento, dove i parametri della richiesta (URL, metodo, intestazioni, parametri, codificatore) vengono passati attraverso chiamate sequenziali. Questo rende il codice più leggibile e riduce la probabilità di errori relativi a una configurazione errata di URLRequest. L'approccio dichiarativo consente di concentrarsi su ciò che deve essere fatto anziché sui dettagli di come configurare la connessione. Lo sviluppatore descrive il risultato desiderato e la libreria gestisce il lavoro di rete di basso livello.

La libreria è stata mantenuta attivamente dal 2014 e ha attraversato sette versioni principali. Alamofire 5, attuale al 2025–2026, include supporto per Combine, async/await, convertitori di risposta, EventMonitor per il debug e RequestInterceptor per intercettare le richieste. Ogni versione principale ha portato miglioramenti significativi: Alamofire 4 ha aggiunto il supporto Codable, Alamofire 5 ha aggiunto Combine Publishers e un sistema di intercettazione delle richieste migliorato.

L'ecosistema Alamofire include librerie aggiuntive: AlamofireImage per il caricamento e la cache delle immagini, AlamofireNetworkActivityIndicator per l'indicatore di rete nella barra di stato iOS e AlamofireObjectMapper per l'integrazione con ObjectMapper. Questi componenti fanno di Alamofire uno stack di rete completo, non solo un client HTTP.

Installazione e configurazione

Alamofire si installa tramite Swift Package Manager (consigliato), CocoaPods o Carthage. In Xcode, basta aprire il menu File → Add Packages, incollare l'URL del repository e specificare la versione.

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

// Importare nel file
import Alamofire

Dopo l'installazione, Alamofire è disponibile globalmente attraverso il namespace AF(abbreviazione di Alamofire) senza configurazione aggiuntiva. La maggior parte dei progetti inizia configurando una Session con le proprie impostazioni — questo consente di impostare un URL di base, intestazioni predefinite, timeout e gestori di certificati TLS.

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

Creare una sessione personalizzata tramite Session(configuration:) è necessario quando è richiesta una configurazione unica per diverse parti dell'applicazione — ad esempio, una sessione separata per i download di immagini con caching aggressivo e un'altra per le richieste API con autenticazione. La Session di Alamofire accetta non solo la configurazione, ma anche un interceptor, serverTrustManager, cachedResponseHandler e redirectHandler, fornendo il controllo completo sul comportamento di rete in tutte le fasi della richiesta.

Caratteristiche principali

Alamofire fornisce un'ampia gamma di funzioni che coprono la maggior parte degli scenari di interazione di rete nelle applicazioni iOS. Vediamo le principali.

Richieste HTTP

La sintassi di base di una richiesta include il metodo, l'URL, i parametri e la codifica. Tutti i metodi HTTP standard sono supportati tramite l'enum HTTPMethod: get, post, put, patch, delete. I parametri possono essere codificati come parametri URL (URLEncoding), corpo JSON (JSONEncoding) o dati 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("Creato dall'utente: \(user)")
        case .failure(let error):
            print("Errore: \(error)")
        }
    }

Il metodo validate() controlla automaticamente il codice di stato (200–299) e il tipo di contenuto, restituendo un errore in caso di risposta inaspettata, eliminando il controllo manuale di statusCode. responseDecodable utilizza il protocollo Decodable per la deserializzazione automatica del JSON in strutture Swift — questo elimina la JSONSerialization manuale e riduce il codice boilerplate quando si lavora con le API REST.

Gestione delle risposte

Alamofire supporta diversi tipi di gestori di risposta: response (dati grezzi), responseJSON (dizionario/array), responseString (testo), responseData (Data) e responseDecodable (modello Decodable). I convertitori di risposta possono essere personalizzati — per protobuf, formati grafici o protocolli personalizzati.

Caricamento e download di file

Per caricare dati sul server si utilizza upload, che supporta Data, File e MultipartFormData. Il download di file di grandi dimensioni avviene tramite download con la possibilità di riprendere attraverso resumeData dopo un'interruzione della connessione. Entrambe le operazioni supportano il monitoraggio dell'avanzamento tramite uploadProgress e downloadProgress con valori frazionari da 0 a 1 per la visualizzazione nell'interfaccia utente.

Il caricamento multiparte con Alamofire è particolarmente conveniente: il metodo upload(multipartFormData:) accetta una closure in cui le parti del modulo vengono aggiunte tramite append. Ogni parte può contenere dati, un file o un flusso, oltre al proprio nome e tipo mime. Alamofire calcola automaticamente i confini multiparte e imposta l'intestazione Content-Type corretta, risparmiando allo sviluppatore la formazione manuale del corpo della richiesta. Per file di grandi dimensioni, si consiglia di utilizzare provider di flusso invece di caricare l'intero file in memoria — questo evita il superamento del limite di memoria sui dispositivi mobili con risorse limitate. Uno scenario tipico è l'invio dell'avatar dell'utente insieme ai dati del profilo in un'unica richiesta multiparte, riducendo il numero di chiamate HTTP e semplificando l'elaborazione lato server.

Alamofire vs URLSession

Confrontare Alamofire con URLSession nativo aiuta a prendere decisioni architetturali. Alamofire non sostituisce URLSession — si costruisce sopra di esso e utilizza gli stessi meccanismi di configurazione, caching e attività in background. Tutte le funzionalità di URLSession sono accessibili tramite Alamofire, ma con una sintassi dichiarativa più comoda.

Nei grandi progetti, Alamofire riduce il codice delle richieste di rete del 30–50% e semplifica la gestione degli errori. Nei piccoli progetti o quando la dimensione del binario è un vincolo rigoroso, URLSession nativo è preferibile per l'assenza di dipendenze esterne.

Alamofire 5 moderno si integra con Combine tramite la proprietà publishDecodable, che restituisce un Publisher, consentendo catene di richieste reattive con gestione degli errori e trasformazione dei dati. Per async/await, sono disponibili metodi con il suffisso value — ad esempio, AF.request(url).serializingDecodable(User.self).value, rendendo la sintassi estremamente concisa e che ricorda il lavoro con URLSession nativo. Quando si utilizza async/await, le closure non sono più necessarie e la gestione degli errori avviene tramite i blocchi do-catch standard di Swift, semplificando la manutenzione e la leggibilità del codice a lungo termine.

Esempi di codice

Consideriamo un esempio più complesso — una richiesta con un intercettatore che aggiunge automaticamente un token di autorizzazione e esegue un tentativo in caso di errore 401. Questo è uno scenario tipico per applicazioni con autenticazione 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)
        }
    }
}

AuthInterceptor implementa due protocolli: adapt (aggiunge un token a ogni richiesta) e retry (tenta di rinnovare il token in caso di errore 401). Il metodo retry controlla il codice di stato della risposta e, se viene ricevuto un 401, richiede un nuovo token tramite TokenManager. Dopo un rinnovo riuscito, la richiesta viene automaticamente ritentata.

Utilizzo dell'intercettatore con una sessione:

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

Tutte le richieste attraverso questa sessione passano automaticamente attraverso AuthInterceptor — il token viene aggiunto alle intestazioni e, in caso di 401, vengono eseguiti rinnovo e tentativo. Questo elimina la duplicazione del codice di autenticazione in ogni richiesta e centralizza la logica di gestione dei token.