Interceptor — ce este, tipurile de interceptoare OkHttp și Alamofire

Ce este Interceptor?

Interceptor — component software introdus în clientul HTTP pentru interceptarea și modificarea cererilor înainte de trimiterea la server și a răspunsurilor înainte de transmiterea către aplicație. În dezvoltarea mobilă, interceptoarele rezolvă sarcini transversale: adăugarea automată a tokenurilor de autentificare, logarea traficului cu măsurarea timpului, reîncercări la erori temporare de rețea, comprimarea și decriptarea datelor din mers. Arhitectura Interceptor se bazează pe pattern-ul Chain of Responsibility — fiecare interceptator poate modifica cererea, o poate executa sau întrerupe lanțul returnând un răspuns personalizat.

Cum funcționează lanțul de interceptoare

În OkHttp, interceptoarele formează un lanț (chain). Fiecare Interceptor primește un obiect Chain cu cererea originală și apelează chain.proceed(request) pentru a transmite controlul următorului interceptator. După primirea răspunsului, interceptatorul poate analiza Response, îl poate modifica, repeta cererea la eroare sau returna un răspuns personalizat pentru cache. Ordinea adăugării interceptoarelor în OkHttpClient.Builder determină succesiunea executării lor: primul adăugat se execută primul la trimitere și ultimul la primire.

Interceptor în OkHttp: Application și Network

OkHttp împarte interceptoarele în două tipuri. Application Interceptor (addInterceptor) se execută între codul aplicației și OkHttp: un apel chain.proceed() — o cerere la server, indiferent de redirecționări. Network Interceptor (addNetworkInterceptor) se execută în interiorul OkHttp după formarea antetelor și conexiunii — se activează la fiecare redirecționare, reîncercare sau autentificare. Această diferență este esențială pentru alegerea corectă a tipului de interceptator pentru o sarcină specifică.

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} în ${duration}ms")
        return response
    }
}

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

LoggingInterceptor — Application Interceptor care loghează metoda, URL, codul răspunsului și timpul de execuție. Adăugarea prin addInterceptor() garantează un singur log per cerere utilizator fără duplicare la redirecționări. CacheInterceptor a fost adăugat ca Network Interceptor pentru a lua în considerare antetele Cache-Control ale serverului, care sunt vizibile doar în interiorul OkHttp după formarea cererii HTTP.

Diferența dintre tipuri în practică

Când aplicația face o cerere, serverul poate răspunde cu o redirecționare 302 sau 301. Application Interceptor va vedea doar răspunsul final după toate redirecționările — nu știe câte cereri intermediare au fost făcute. Network Interceptor va vedea fiecare cerere și răspuns, inclusiv pe cele intermediare. Conform datelor Square (2026), Network Interceptor vede și datele comprimate la nivelul conexiunii (gzip), în timp ce Application Interceptor primește răspunsul deja decomprimat. Pentru numărarea numărului real de apeluri de rețea utilizați Network Interceptor.

Alamofire RequestInterceptor

Alamofire oferă protocolul RequestInterceptor, care combină două protocoale: RequestAdapter pentru modificarea cererii înainte de trimitere și RequestRetrier pentru reîncercări la erori. Această separare permite combinarea flexibilă a adaptării (adăugarea antetelor, tokenurilor) cu politica de reîncercări (întârziere exponențială, limită de încercări, verificarea tipului de eroare). RequestInterceptor este implementat de o singură structură sau clasă care implementează ambele protocoale.

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 în Swift adaugă token Bearer prin adapt și reîncearcă automat cererea la URLError (pierdere rețea, timeout) prin retry cu o întârziere de 1 secundă. Separarea adaptării și reîncercărilor permite testarea lor independentă — se poate scrie un test unitar pentru adaptare fără a afecta logica retry. Conform datelor Alamofire (2026), RequestInterceptor este modul standard de gestionare centralizată a autentificării în proiectele iOS.

Scenarii de utilizare a interceptoarelor

Logarea — cel mai frecvent scenariu. Interceptor înregistrează URL, metoda, antetele, corpul cererii și răspunsului, timpul de execuție. În compilările de debug, acesta înlocuiește Charles Proxy și Wireshark, în release — ajută rapoartele de erori cu contextul cererii. Pentru OkHttp se utilizează HttpLoggingInterceptor din biblioteca logging-interceptor cu nivelurile NONE, BASIC, HEADERS și BODY. Nivelul BODY loghează corpurile complete ale cererilor și răspunsurilor — utilizați doar în debug.

Autentificarea și Refresh Token

Când tokenul de acces expiră, Interceptor interceptează răspunsul 401, apelează refresh token API și reexecută cererea originală cu noul token. În OkHttp acest lucru se implementează prin Authenticator sau un Interceptor personalizat cu verificarea response.code. Authenticator are acces doar la antetele răspunsului, Interceptor — la corpul complet. În Alamofire — prin RequestRetrier, care returnează .retry după reîmprospătarea tokenului. Conform datelor OWASP (2026), reîmprospătarea automată a tokenurilor prin Interceptor reduce riscul de scurgere a datelor de autentificare.

Adăugarea antetelor comune

Content-Type, Accept-Language, User-Agent, Device-ID — antete necesare în fiecare cerere. Interceptor le adaugă centralizat, fără duplicare în fiecare metodă API. User-Agent se formează o dată la pornirea aplicației: „AppName/1.0 (Android 14; Pixel 8)". Accept-Language se preia din limba de sistem a dispozitivului. Conform datelor Alamofire (2026), gestionarea centralizată a antetelor prin Interceptor reduce numărul erorilor de antete incorecte cu 30%.

Cele mai bune practici și ordinea lanțului

Ordinea adăugării Interceptor în OkHttp determină comportamentul întregului lanț. Primul interceptator adăugat se execută primul la trimiterea cererii și ultimul la primirea răspunsului. Pentru logare adăugați Interceptor primul — va vedea cererea finală cu toate modificările de la celelalte interceptoare. Pentru comprimare — ultimul, pentru ca comprimarea să se aplice datelor finale. Pentru autentificare — înainte de reîncercare, pentru ca tokenul să se reîmprospăteze înainte de reîncercare.

Recomandări pentru compilările de producție

În compilările release, dezactivați logarea prin BuildConfig.DEBUG sau injectarea dependențelor. Utilizați addNetworkInterceptor pentru cache — Network Interceptor vede antetele Cache-Control ale serverului și interpretează corect politica de cache. Pentru autentificare aplicați addInterceptor (Application) — acest lucru previne re-interceptarea la redirecționările către domenii externe, unde antetele de autorizare nu trebuie trimise. Testați fiecare Interceptor izolat cu MockWebServer din okhttp-testing-support — acesta interceptează cererile și returnează răspunsuri pregătite în prealabil, permițând verificarea logicii interceptatorului fără un server real.

Performanța Interceptor

Fiecare Interceptor adaugă o întârziere mică la timpul cererii. Într-un lanț tipic de 3–4 interceptoare (logare, autentificare, comprimare, cache) suprasarcina este mai mică de 5 milisecunde per cerere. Problemele încep când Interceptor execută operații blocante: apel sincron refresh token API, scrierea logurilor mari în fișier sau criptarea corpului cererii. Toate aceste operații trebuie să fie asincrone sau executate într-un thread de fundal. Conform datelor Square (2026), OkHttp execută Interceptor în pool-ul de thread-uri Dispatcher — blocarea unui interceptator întârzie întregul lanț.

• Ordinea contează — logare prima, autentificare înainte de reîncercare, comprimare ultima
• Debug vs Release — HttpLoggingInterceptor doar în compilările debug
• Izolare — fiecare Interceptor rezolvă o singură sarcină (Single Responsibility)
• Asincronism — Interceptor se execută pe thread-ul de fundal OkHttp, fără a bloca UI