Interceptor — cos’è, tipi di intercettatori OkHttp e Alamofire

Cos’è un Interceptor?

Interceptor è un componente software iniettato in un client HTTP per intercettare e modificare le richieste prima dell’invio al server e le risposte prima che raggiungano l’applicazione. Nello sviluppo mobile, gli intercettatori gestiscono preoccupazioni trasversali: iniezione automatica di token di autenticazione, logging del traffico con misurazioni temporali, tentativi in caso di errori di rete temporanei, compressione e decifratura dei dati al volo. L’architettura Interceptor si basa sul pattern Chain of Responsibility — ogni intercettatore può modificare la richiesta, eseguirla o interrompere la catena restituendo una risposta personalizzata.

Come funziona la catena di intercettatori

In OkHttp, gli intercettatori formano una catena. Ogni Interceptor riceve un oggetto Chain con la richiesta originale e chiama chain.proceed(request) per passare il controllo all’intercettatore successivo. Dopo aver ricevuto la risposta, l’intercettatore può analizzare la Response, modificarla, ripetere la richiesta in caso di errore o restituire una risposta personalizzata per il caching. L’ordine di aggiunta degli intercettatori a OkHttpClient.Builder determina il loro ordine di esecuzione: il primo aggiunto viene eseguito per primo all’invio e per ultimo alla ricezione.

Interceptor in OkHttp: Application e Network

OkHttp separa gli intercettatori in due tipi. Application Interceptor (addInterceptor) viene eseguito tra il codice dell’applicazione e OkHttp: una chiamata chain.proceed() — una richiesta al server, indipendentemente dai reindirizzamenti. Network Interceptor (addNetworkInterceptor) viene eseguito all’interno di OkHttp dopo la formazione delle intestazioni e la connessione — si attiva a ogni reindirizzamento, tentativo o autenticazione. Questa distinzione è fondamentale per scegliere il tipo di intercettatore giusto per un compito specifico.

class LoggingInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        Log.d("HTTP", "${request.method} ${request.url}")

        val startTime = System.currentTimeMillis()
        val response = chain.proceed(request)
        val duration = System.currentTimeMillis() - startTime

        Log.d("HTTP", "${response.code} in ${duration}ms")
        return response
    }
}

val client = OkHttpClient.Builder()
    .addInterceptor(LoggingInterceptor())
    .addNetworkInterceptor(CacheInterceptor())
    .build()

LoggingInterceptor — un Application Interceptor che registra metodo, URL, codice di risposta e tempo di esecuzione. Aggiungerlo tramite addInterceptor() garantisce un log per richiesta utente senza duplicazione nei reindirizzamenti. CacheInterceptor viene aggiunto come Network Interceptor per tenere conto delle intestazioni Cache-Control del server, visibili solo all’interno di OkHttp dopo la formazione della richiesta HTTP.

Differenza tra i tipi nella pratica

Quando l’applicazione effettua una richiesta, il server può rispondere con un reindirizzamento 302 o 301. Application Interceptor vede solo la risposta finale dopo tutti i reindirizzamenti — non sa quante richieste intermedie sono state effettuate. Network Interceptor vede ogni richiesta e risposta, incluse quelle intermedie. Secondo Square (2026), Network Interceptor vede anche i dati compressi a livello di connessione (gzip), mentre Application Interceptor riceve la risposta già decompressa. Per contare il numero effettivo di chiamate di rete, usa Network Interceptor.

Alamofire RequestInterceptor

Alamofire fornisce il protocollo RequestInterceptor, che combina due protocolli: RequestAdapter per modificare la richiesta prima dell’invio e RequestRetrier per tentativi in caso di errore. Questa separazione consente di combinare flessibilmente l’adattamento (aggiunta di intestazioni, token) con la politica di tentativi (backoff esponenziale, limite di tentativi, controllo del tipo di errore). RequestInterceptor è implementato da un’unica struttura o classe che è conforme a entrambi i protocolli.

struct AuthInterceptor: RequestInterceptor {
    private let tokenProvider: TokenProvider

    func adapt(_ urlRequest: URLRequest,
                using state: Session.RequestAdapterState,
                completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(tokenProvider.token)",
                        forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
               for session: Session,
               dueTo error: Error,
               completion: @escaping (RetryResult) -> Void) {
        if error is URLError {
            completion(.retryWithDelay(1))
        } else {
            completion(.doNotRetry)
        }
    }
}

AuthInterceptor su Swift aggiunge un token Bearer tramite adapt e ripete automaticamente la richiesta in caso di URLError (perdita di rete, timeout) tramite retry con un ritardo di 1 secondo. Separare adattamento e tentativi consente di testarli indipendentemente — puoi scrivere un test unitario per l’adattamento senza influenzare la logica di tentativo. Secondo Alamofire (2026), RequestInterceptor è il modo standard per centralizzare la gestione dell’autenticazione nei progetti iOS.

Casi d’uso degli intercettatori

Logging — il caso d’uso più comune. L’Interceptor registra URL, metodo, intestazioni, corpo della richiesta e della risposta e tempo di esecuzione. Nelle build di debug, questo sostituisce Charles Proxy e Wireshark; nelle build di rilascio, aiuta i rapporti di crash con il contesto della richiesta. OkHttp utilizza HttpLoggingInterceptor dalla libreria logging-interceptor con livelli NONE, BASIC, HEADERS e BODY. Il livello BODY registra i corpi completi delle richieste e risposte — usa solo in debug.

Autenticazione e rinnovo del token

Quando il token di accesso scade, l’Interceptor intercetta la risposta 401, chiama l’API di rinnovo del token e ripete la richiesta originale con il nuovo token. In OkHttp, ciò viene implementato tramite Authenticator o un Interceptor personalizzato con controllo di response.code. L’Authenticator ha accesso solo alle intestazioni della risposta, mentre l’Interceptor ha accesso al corpo completo. In Alamofire — tramite RequestRetrier, restituendo .retry dopo il rinnovo del token. Secondo OWASP (2026), il rinnovo automatico dei token tramite Interceptor riduce il rischio di perdita di credenziali.

Aggiungere intestazioni comuni

Content-Type, Accept-Language, User-Agent, Device-ID — intestazioni richieste in ogni richiesta. L’Interceptor le aggiunge centralmente, senza duplicazione in ogni metodo API. User-Agent viene formato una volta all’avvio dell’app: “AppName/1.0 (Android 14; Pixel 8)”. Accept-Language viene preso dalla lingua di sistema del dispositivo. Secondo Alamofire (2026), la gestione centralizzata delle intestazioni tramite Interceptor riduce gli errori di intestazione errate del 30%.

Best practice e ordine della catena

L’ordine di aggiunta degli Interceptors in OkHttp determina il comportamento dell’intera catena. Il primo intercettatore aggiunto viene eseguito per primo all’invio della richiesta e per ultimo alla ricezione della risposta. Per il logging, aggiungi l’Interceptor per primo — vedrà la richiesta finale con tutte le modifiche degli altri intercettatori. Per la compressione, aggiungilo per ultimo in modo che la compressione venga applicata ai dati finali. Per l’autenticazione, aggiungilo prima del tentativo in modo che il token venga rinnovato prima del prossimo tentativo.

Raccomandazioni per le build di produzione

Nelle build di rilascio, disabilita il logging tramite BuildConfig.DEBUG o l’iniezione di dipendenze. Usa addNetworkInterceptor per il caching — Network Interceptor vede le intestazioni Cache-Control del server e interpreta correttamente la politica di caching. Per l’autenticazione, usa addInterceptor (Application) — questo previene la reintercettazione nei reindirizzamenti verso domini di terze parti dove le intestazioni di autorizzazione non dovrebbero essere inviate. Testa ogni Interceptor isolatamente usando MockWebServer da okhttp-testing-support — intercetta le richieste e restituisce risposte pre-preparate, consentendoti di verificare la logica dell’intercettatore senza un server reale.

Prestazioni dell’Interceptor

Ogni Interceptor aggiunge un piccolo ritardo al tempo di richiesta. In una catena tipica di 3-4 intercettatori (logging, autenticazione, compressione, caching), l’overhead è inferiore a 5 millisecondi per richiesta. I problemi sorgono quando un Interceptor esegue operazioni bloccanti: chiamata sincrona all’API di rinnovo del token, scrittura di log grandi in un file o crittografia del corpo della richiesta. Tutte queste operazioni dovrebbero essere asincrone o eseguite in un thread in background. Secondo Square (2026), OkHttp esegue gli Interceptors nel pool di thread Dispatcher — bloccare un intercettatore ritarda l’intera catena.

• L’ordine conta — logging primo, autenticazione prima del tentativo, compressione ultima
• Debug vs Release — HttpLoggingInterceptor solo nelle build di debug
• Isolamento — ogni Interceptor gestisce un compito (Responsabilità Singola)
• Asincronicità — Interceptor viene eseguito nel thread in background di OkHttp, senza bloccare l’UI