Interceptor — qué es, tipos de interceptores OkHttp y Alamofire

¿Qué es un Interceptor?

Interceptor es un componente de software inyectado en un cliente HTTP para interceptar y modificar peticiones antes de enviarlas al servidor y respuestas antes de que lleguen a la aplicación. En el desarrollo móvil, los interceptores manejan tareas transversales: inyección automática de tokens de autenticación, registro de tráfico con mediciones de tiempo, reintentos en errores temporales de red y compresión y descifrado de datos sobre la marcha. La arquitectura Interceptor se basa en el patrón Chain of Responsibility — cada interceptor puede modificar la petición, ejecutarla o interrumpir la cadena devolviendo una respuesta personalizada.

Cómo funciona la cadena de interceptores

En OkHttp, los interceptores forman una cadena. Cada Interceptor recibe un objeto Chain con la petición original y llama a chain.proceed(request) para pasar el control al siguiente interceptor. Tras recibir la respuesta, el interceptor puede analizar la Response, modificarla, reintentar la petición en caso de error o devolver una respuesta personalizada para el almacenamiento en caché. El orden en que se añaden los interceptores al OkHttpClient.Builder determina su orden de ejecución: el primero añadido se ejecuta primero al enviar y último al recibir.

Interceptor en OkHttp: Application y Network

OkHttp separa los interceptores en dos tipos. Application Interceptor (addInterceptor) se ejecuta entre el código de la aplicación y OkHttp: una llamada a chain.proceed() — una petición al servidor, independientemente de las redirecciones. Network Interceptor (addNetworkInterceptor) se ejecuta dentro de OkHttp tras la formación de cabeceras y conexión — se activa en cada redirección, reintento o intento de autenticación. Esta distinción es crítica para elegir el tipo de interceptor adecuado para una tarea específica.

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

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

LoggingInterceptor — un Application Interceptor que registra el método, URL, código de respuesta y tiempo de ejecución. Añadirlo mediante addInterceptor() garantiza un registro por petición de usuario sin duplicación en redirecciones. CacheInterceptor se añade como Network Interceptor para tener en cuenta las cabeceras Cache-Control del servidor, que solo son visibles dentro de OkHttp tras formarse la petición HTTP.

Diferencia entre tipos en la práctica

Cuando la aplicación realiza una petición, el servidor puede responder con una redirección 302 o 301. Application Interceptor solo ve la respuesta final después de todas las redirecciones — no sabe cuántas peticiones intermedias se hicieron. Network Interceptor ve cada petición y respuesta, incluidas las intermedias. Según Square (2026), Network Interceptor también ve los datos comprimidos a nivel de conexión (gzip), mientras que Application Interceptor recibe la respuesta ya descomprimida. Para contar el número real de llamadas de red, usa Network Interceptor.

Alamofire RequestInterceptor

Alamofire proporciona el protocolo RequestInterceptor, que combina dos protocolos: RequestAdapter para modificar la petición antes de enviarla y RequestRetrier para reintentos en caso de error. Esta separación permite combinar de forma flexible la adaptación (añadir cabeceras, tokens) con la política de reintentos (espera exponencial, límite de intentos, comprobación del tipo de error). RequestInterceptor se implementa mediante una única estructura o clase que conforme ambos protocolos.

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 en Swift añade un token Bearer mediante adapt y reintenta automáticamente la petición en caso de URLError (pérdida de red, tiempo de espera) a través de retry con un retardo de 1 segundo. Separar la adaptación y los reintentos permite probarlos de forma independiente — puedes escribir una prueba unitaria para la adaptación sin afectar la lógica de reintentos. Según Alamofire (2026), RequestInterceptor es la forma estándar de centralizar la gestión de autenticación en proyectos iOS.

Casos de uso de interceptores

Registro — el caso de uso más común. El Interceptor registra la URL, método, cabeceras, cuerpo de la petición y respuesta, y tiempo de ejecución. En compilaciones de depuración, esto reemplaza a Charles Proxy y Wireshark; en compilaciones de lanzamiento, ayuda a los informes de fallos con contexto de la petición. OkHttp utiliza HttpLoggingInterceptor de la librería logging-interceptor con niveles NONE, BASIC, HEADERS y BODY. El nivel BODY registra los cuerpos completos de peticiones y respuestas — úsalo solo en depuración.

Autenticación y renovación de token

Cuando el token de acceso caduca, el Interceptor intercepta la respuesta 401, llama a la API de renovación de token y reintenta la petición original con el nuevo token. En OkHttp, esto se implementa mediante Authenticator o un Interceptor personalizado con comprobación de response.code. El Authenticator solo tiene acceso a las cabeceras de la respuesta, mientras que el Interceptor tiene acceso al cuerpo completo. En Alamofire — mediante RequestRetrier, devolviendo .retry tras la renovación del token. Según OWASP (2026), la renovación automática de tokens mediante Interceptor reduce el riesgo de fuga de credenciales.

Añadir cabeceras comunes

Content-Type, Accept-Language, User-Agent, Device-ID — cabeceras requeridas en cada petición. El Interceptor las añade de forma centralizada, sin duplicación en cada método de API. User-Agent se forma una vez al iniciar la aplicación: “AppName/1.0 (Android 14; Pixel 8)”. Accept-Language se toma del idioma del sistema del dispositivo. Según Alamofire (2026), la gestión centralizada de cabeceras mediante Interceptor reduce los errores de cabeceras incorrectas en un 30%.

Mejores prácticas y orden de la cadena

El orden de añadir Interceptors en OkHttp determina el comportamiento de toda la cadena. El primer interceptor añadido se ejecuta primero al enviar la petición y último al recibir la respuesta. Para registro, añade el Interceptor primero — verá la petición final con todas las modificaciones de otros interceptores. Para compresión, añádelo último para que la compresión se aplique a los datos finales. Para autenticación, añádelo antes del reintento para que el token se renueve antes del siguiente intento.

Recomendaciones para compilaciones de producción

En compilaciones de lanzamiento, desactiva el registro mediante BuildConfig.DEBUG o inyección de dependencias. Usa addNetworkInterceptor para el almacenamiento en caché — Network Interceptor ve las cabeceras Cache-Control del servidor e interpreta correctamente la política de caché. Para autenticación, usa addInterceptor (Application) — esto evita la reintercepción en redirecciones a dominios de terceros donde no deben enviarse cabeceras de autorización. Prueba cada Interceptor de forma aislada con MockWebServer de okhttp-testing-support — intercepta peticiones y devuelve respuestas preparadas, permitiéndote verificar la lógica del interceptor sin un servidor real.

Rendimiento del Interceptor

Cada Interceptor añade un pequeño retardo al tiempo de petición. En una cadena típica de 3-4 interceptores (registro, autenticación, compresión, caché), la sobrecarga es inferior a 5 milisegundos por petición. Los problemas surgen cuando un Interceptor realiza operaciones bloqueantes: llamada síncrona a la API de renovación de token, escritura de registros grandes en un archivo o cifrado del cuerpo de la petición. Todas estas operaciones deben ser asíncronas o ejecutarse en un hilo en segundo plano. Según Square (2026), OkHttp ejecuta los Interceptors en el grupo de hilos Dispatcher — bloquear un interceptor retrasa toda la cadena.

• El orden importa — registro primero, autenticación antes del reintento, compresión al final
• Debug vs Release — HttpLoggingInterceptor solo en compilaciones de depuración
• Aislamiento — cada Interceptor maneja una tarea (Responsabilidad Única)
• Asincronía — Interceptor se ejecuta en el hilo en segundo plano de OkHttp, sin bloquear la UI