Interceptor — co to jest, rodzaje przechwytywaczy OkHttp i Alamofire

Czym jest Interceptor?

Interceptor — komponent programowy wdrażany w kliencie HTTP do przechwytywania i modyfikacji żądań przed wysłaniem na serwer oraz odpowiedzi przed przekazaniem do aplikacji. W programowaniu mobilnym przechwytywacze rozwiązują zadania przekrojowe: automatyczne dodawanie tokenów uwierzytelniających, logowanie ruchu z pomiarem czasu, ponowne próby przy tymczasowych błędach sieci, kompresja i deszyfrowanie danych w locie. Architektura Interceptor opiera się na wzorcu Chain of Responsibility — każdy przechwytywacz może zmodyfikować żądanie, wykonać je lub przerwać łańcuch, zwracając niestandardową odpowiedź.

Jak działa łańcuch przechwytywaczy

W OkHttp przechwytywacze tworzą łańcuch (chain). Każdy Interceptor otrzymuje obiekt Chain z oryginalnym żądaniem i wywołuje chain.proceed(request), aby przekazać sterowanie do następnego przechwytywacza. Po otrzymaniu odpowiedzi przechwytywacz może przeanalizować Response, zmodyfikować go, powtórzyć żądanie przy błędzie lub zwrócić niestandardową odpowiedź do buforowania. Kolejność dodawania przechwytywaczy w OkHttpClient.Builder określa porządek ich wykonania: pierwszy dodany wykonuje się jako pierwszy przy wysyłaniu i jako ostatni przy odbieraniu.

Interceptor w OkHttp: Application i Network

OkHttp dzieli przechwytywacze na dwa typy. Application Interceptor (addInterceptor) wykonuje się między kodem aplikacji a OkHttp: jedno wywołanie chain.proceed() — jedno żądanie na serwer, niezależnie od przekierowań. Network Interceptor (addNetworkInterceptor) wykonuje się wewnątrz OkHttp po utworzeniu nagłówków i połączenia — uruchamia się przy każdym przekierowaniu, ponowieniu lub uwierzytelnianiu. Ta różnica jest krytyczna dla prawidłowego wyboru typu przechwytywacza do konkretnego zadania.

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

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

LoggingInterceptor — Application Interceptor logujący metodę, URL, kod odpowiedzi i czas wykonania. Dodanie przez addInterceptor() gwarantuje jeden log na żądanie użytkownika bez duplikowania przy przekierowaniach. CacheInterceptor został dodany jako Network Interceptor, aby uwzględniać nagłówki Cache-Control serwera, które są widoczne tylko wewnątrz OkHttp po utworzeniu żądania HTTP.

Różnica między typami w praktyce

Gdy aplikacja wysyła żądanie, serwer może odpowiedzieć przekierowaniem 302 lub 301. Application Interceptor zobaczy tylko końcową odpowiedź po wszystkich przekierowaniach — nie wie, ile pośrednich żądań zostało wykonanych. Network Interceptor zobaczy każde żądanie i odpowiedź, włącznie z pośrednimi. Według danych Square (2026), Network Interceptor widzi również dane skompresowane na poziomie połączenia (gzip), podczas gdy Application Interceptor otrzymuje już rozpakowaną odpowiedź. Do zliczania rzeczywistej liczby wywołań sieciowych używaj Network Interceptor.

Alamofire RequestInterceptor

Alamofire udostępnia protokół RequestInterceptor, łączący dwa protokoły: RequestAdapter do modyfikacji żądania przed wysłaniem i RequestRetrier do ponownych prób przy błędach. Takie rozdzielenie pozwala elastycznie łączyć adaptację (dodawanie nagłówków, tokenów) z polityką ponowień (opóźnienie wykładnicze, limit prób, sprawdzanie typu błędu). RequestInterceptor jest implementowany przez jedną strukturę lub klasę implementującą oba protokoły.

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 w Swift dodaje token Bearer przez adapt i automatycznie ponawia żądanie przy URLError (utrata sieci, timeout) przez retry z opóźnieniem 1 sekunda. Rozdzielenie adaptacji i ponowień pozwala testować je niezależnie — można napisać test jednostkowy na adaptację bez wpływania na logikę retry. Według danych Alamofire (2026), RequestInterceptor to standardowy sposób scentralizowanego zarządzania uwierzytelnianiem w projektach iOS.

Scenariusze użycia przechwytywaczy

Logowanie — najczęstszy scenariusz. Interceptor zapisuje URL, metodę, nagłówki, treść żądania i odpowiedzi, czas wykonania. W kompilacjach debugowych zastępuje Charles Proxy i Wireshark, w release — pomaga raportom błędów z kontekstem żądania. Dla OkHttp używa się HttpLoggingInterceptor z biblioteki logging-interceptor z poziomami NONE, BASIC, HEADERS i BODY. Poziom BODY loguje pełne treści żądań i odpowiedzi — używaj tylko w debug.

Uwierzytelnianie i Refresh Token

Gdy access token wygasa, Interceptor przechwytuje odpowiedź 401, wywołuje refresh token API i ponawia oryginalne żądanie z nowym tokenem. W OkHttp jest to realizowane przez Authenticator lub niestandardowy Interceptor ze sprawdzaniem response.code. Authenticator ma dostęp tylko do nagłówków odpowiedzi, Interceptor — do pełnej treści. W Alamofire — przez RequestRetrier, zwracający .retry po odświeżeniu tokena. Według danych OWASP (2026), automatyczne odświeżanie tokenów przez Interceptor zmniejsza ryzyko wycieku danych uwierzytelniających.

Dodawanie wspólnych nagłówków

Content-Type, Accept-Language, User-Agent, Device-ID — nagłówki wymagane w każdym żądaniu. Interceptor dodaje je centralnie, bez powielania w każdej metodzie API. User-Agent jest tworzony jeden raz przy starcie aplikacji: „AppName/1.0 (Android 14; Pixel 8)". Accept-Language pobierany jest z języka systemowego urządzenia. Według danych Alamofire (2026), scentralizowane zarządzanie nagłówkami przez Interceptor zmniejsza liczbę błędów nieprawidłowych nagłówków o 30%.

Najlepsze praktyki i kolejność łańcucha

Kolejność dodawania Interceptor w OkHttp określa zachowanie całego łańcucha. Pierwszy dodany przechwytywacz wykonuje się jako pierwszy przy wysyłaniu żądania i jako ostatni przy odbieraniu odpowiedzi. Do logowania dodawaj Interceptor jako pierwszy — zobaczy końcowe żądanie ze wszystkimi modyfikacjami od innych przechwytywaczy. Do kompresji — jako ostatni, aby kompresja była stosowana do końcowych danych. Do uwierzytelniania — przed ponowieniem, aby token odświeżał się przed ponowną próbą.

Zalecenia dla kompilacji produkcyjnych

W kompilacjach release wyłączaj logowanie przez BuildConfig.DEBUG lub wstrzykiwanie zależności. Używaj addNetworkInterceptor do buforowania — Network Interceptor widzi nagłówki Cache-Control serwera i poprawnie interpretuje politykę buforowania. Do uwierzytelniania stosuj addInterceptor (Application) — zapobiega to ponownemu przechwytywaniu przy przekierowaniach do zewnętrznych domen, gdzie nagłówki autoryzacji nie powinny być wysyłane. Testuj każdy Interceptor izolowanie za pomocą MockWebServer z okhttp-testing-support — przechwytuje żądania i zwraca wcześniej przygotowane odpowiedzi, pozwalając sprawdzić logikę przechwytywacza bez rzeczywistego serwera.

Wydajność Interceptor

Każdy Interceptor dodaje niewielkie opóźnienie do czasu żądania. W typowym łańcuchu 3–4 przechwytywaczy (logowanie, uwierzytelnianie, kompresja, buforowanie) narzut wynosi mniej niż 5 milisekund na żądanie. Problemy zaczynają się, gdy Interceptor wykonuje operacje blokujące: synchroniczne wywołanie refresh token API, zapis dużych logów do pliku lub szyfrowanie treści żądania. Wszystkie te operacje powinny być asynchroniczne lub wykonywane w wątku tła. Według danych Square (2026), OkHttp wykonuje Interceptor w puli wątków Dispatcher — zablokowanie jednego przechwytywacza opóźnia cały łańcuch.

• Kolejność ma znaczenie — logowanie jako pierwsze, uwierzytelnianie przed ponowieniem, kompresja jako ostatnia
• Debug vs Release — HttpLoggingInterceptor tylko w kompilacjach debug
• Izolacja — każdy Interceptor rozwiązuje jedno zadanie (Single Responsibility)
• Asynchroniczność — Interceptor wykonuje się w wątku tła OkHttp, nie blokując UI