Interceptor — какво е, видове прихващачи OkHttp и Alamofire

Какво е Interceptor?

Interceptor — софтуерен компонент, вграждан в HTTP клиента за прихващане и модифициране на заявки преди изпращане към сървъра и отговори преди предаване към приложението. В мобилната разработка прихващачите решават междусекторни задачи: автоматично добавяне на токени за удостоверяване, логване на трафик с измерване на време, повторни опити при временни мрежови грешки, компресия и декриптиране на данни в движение. Архитектурата на Interceptor се основава на шаблона Chain of Responsibility — всеки прихващач може да модифицира заявката, да я изпълни или да прекъсне веригата, връщайки персонализиран отговор.

Как работи веригата от прихващачи

В OkHttp прихващачите образуват верига (chain). Всеки Interceptor получава обект Chain с оригиналната заявка и извиква chain.proceed(request) за предаване на контрола на следващия прихващач. След получаване на отговора, прихващачът може да анализира Response, да го модифицира, да повтори заявката при грешка или да върне персонализиран отговор за кеширане. Редът на добавяне на прихващачи в OkHttpClient.Builder определя реда на тяхното изпълнение: първият добавен се изпълнява пръв при изпращане и последен при получаване.

Interceptor в OkHttp: Application и Network

OkHttp разделя прихващачите на два вида. Application Interceptor (addInterceptor) се изпълнява между кода на приложението и OkHttp: едно извикване на chain.proceed() — една заявка към сървъра, независимо от пренасочванията. Network Interceptor (addNetworkInterceptor) се изпълнява вътре в OkHttp след формиране на заглавията и връзката — задейства се при всяко пренасочване, повторен опит или удостоверяване. Тази разлика е критична за правилния избор на тип прихващач за конкретна задача.

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

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

LoggingInterceptor — Application Interceptor, който логва метода, URL, кода на отговора и времето за изпълнение. Добавянето чрез addInterceptor() гарантира един лог на потребителска заявка без дублиране при пренасочвания. CacheInterceptor е добавен като Network Interceptor, за да вземе предвид Cache-Control заглавията на сървъра, които са видими само вътре в OkHttp след формиране на HTTP заявката.

Разлика между видовете на практика

Когато приложението прави заявка, сървърът може да отговори с пренасочване 302 или 301. Application Interceptor ще види само крайния отговор след всички пренасочвания — не знае колко междинни заявки са направени. Network Interceptor ще види всяка заявка и отговор, включително междинните. Според данни на Square (2026), Network Interceptor също вижда данни, компресирани на ниво връзка (gzip), докато Application Interceptor получава вече декомпресиран отговор. За преброяване на реалния брой мрежови извиквания използвайте Network Interceptor.

Alamofire RequestInterceptor

Alamofire предоставя протокола RequestInterceptor, който съчетава два протокола: RequestAdapter за модифициране на заявката преди изпращане и RequestRetrier за повторни опити при грешки. Това разделяне позволява гъвкаво комбиниране на адаптацията (добавяне на заглавия, токени) с политиката за повторни опити (експоненциално забавяне, лимит на опитите, проверка на типа грешка). RequestInterceptor се имплементира от една структура или клас, имплементиращ и двата протокола.

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 в Swift добавя Bearer токен чрез adapt и автоматично повтаря заявката при URLError (загуба на мрежа, timeout) чрез retry със закъснение от 1 секунда. Разделянето на адаптацията и повторните опити позволява независимото им тестване — може да се напише unit тест за адаптация, без да се засяга retry логиката. Според данни на Alamofire (2026), RequestInterceptor е стандартният начин за централизирано управление на удостоверяването в iOS проекти.

Сценарии за използване на прихващачи

Логване — най-честият сценарий. Interceptor записва URL, метода, заглавията, тялото на заявката и отговора, времето за изпълнение. В debug компилации това замества Charles Proxy и Wireshark, в release — помага на докладите за грешки с контекст на заявката. За OkHttp се използва HttpLoggingInterceptor от библиотеката logging-interceptor с нива NONE, BASIC, HEADERS и BODY. Ниво BODY логва пълните тела на заявки и отговори — използвайте само в debug.

Удостоверяване и Refresh Token

Когато access token изтече, Interceptor прихваща отговора 401, извиква refresh token API и повтаря оригиналната заявка с новия токен. В OkHttp това се имплементира чрез Authenticator или персонализиран Interceptor с проверка на response.code. Authenticator има достъп само до заглавията на отговора, Interceptor — до пълното тяло. В Alamofire — чрез RequestRetrier, който връща .retry след обновяване на токена. Според данни на OWASP (2026), автоматичното обновяване на токени чрез Interceptor намалява риска от изтичане на идентификационни данни.

Добавяне на общи заглавия

Content-Type, Accept-Language, User-Agent, Device-ID — заглавия, необходими във всяка заявка. Interceptor ги добавя централизирано, без дублиране във всеки API метод. User-Agent се формира веднъж при стартиране на приложението: «AppName/1.0 (Android 14; Pixel 8)». Accept-Language се взема от системния език на устройството. Според данни на Alamofire (2026), централизираното управление на заглавия чрез Interceptor намалява броя на грешките с неправилни заглавия с 30%.

Най-добри практики и ред на веригата

Редът на добавяне на Interceptor в OkHttp определя поведението на цялата верига. Първият добавен прихващач се изпълнява пръв при изпращане на заявката и последен при получаване на отговора. За логване добавете Interceptor пръв — ще види крайната заявка с всички модификации от другите прихващачи. За компресия — последен, за да се приложи компресия върху крайните данни. За удостоверяване — преди повторен опит, за да се обнови токенът преди повторния опит.

Препоръки за production компилации

В release компилации изключете логването чрез BuildConfig.DEBUG или инжектиране на зависимости. Използвайте addNetworkInterceptor за кеширане — Network Interceptor вижда Cache-Control заглавията на сървъра и правилно интерпретира политиката за кеширане. За удостоверяване приложете addInterceptor (Application) — това предотвратява повторно прихващане при пренасочвания към външни домейни, където заглавията за оторизация не трябва да се изпращат. Тествайте всеки Interceptor изолирано с MockWebServer от okhttp-testing-support — той прихваща заявки и връща предварително подготвени отговори, позволявайки проверка на логиката на прихващача без реален сървър.

Производителност на Interceptor

Всеки Interceptor добавя малко закъснение към времето на заявката. В типична верига от 3–4 прихващача (логване, удостоверяване, компресия, кеширане) допълнителното натоварване е по-малко от 5 милисекунди на заявка. Проблемите започват, когато Interceptor изпълнява блокиращи операции: синхронно извикване на refresh token API, запис на големи логове във файл или криптиране на тялото на заявката. Всички тези операции трябва да бъдат асинхронни или да се изпълняват във фонова нишка. Според данни на Square (2026), OkHttp изпълнява Interceptor в пула от нишки Dispatcher — блокирането на един прихващач забавя цялата верига.

• Редът има значение — логване първо, удостоверяване преди повторен опит, компресия последна
• Debug срещу Release — HttpLoggingInterceptor само в debug компилации
• Изолация — всеки Interceptor решава една задача (Single Responsibility)
• Асинхронност — Interceptor се изпълнява на фоновата нишка на OkHttp, без да блокира UI