Interceptor — o que é, tipos de interceptadores OkHttp e Alamofire

O que é um Interceptor?

Interceptor é um componente de software injetado em um cliente HTTP para interceptar e modificar requisições antes de serem enviadas ao servidor e respostas antes de chegarem à aplicação. No desenvolvimento móvel, interceptadores lidam com preocupações transversais: injeção automática de tokens de autenticação, logging de tráfego com medições de tempo, repetições em erros temporários de rede e compressão e descriptografia de dados em tempo real. A arquitetura Interceptor é baseada no padrão Chain of Responsibility — cada interceptador pode modificar a requisição, executá-la ou interromper a cadeia retornando uma resposta personalizada.

Como funciona a cadeia de interceptadores

No OkHttp, interceptadores formam uma cadeia. Cada Interceptor recebe um objeto Chain com a requisição original e chama chain.proceed(request) para passar o controle ao próximo interceptador. Após receber a resposta, o interceptador pode analisar a Response, modificá-la, repetir a requisição em caso de erro ou retornar uma resposta personalizada para cache. A ordem de adição dos interceptadores ao OkHttpClient.Builder determina sua ordem de execução: o primeiro adicionado executa primeiro ao enviar e último ao receber.

Interceptor no OkHttp: Application e Network

OkHttp separa interceptadores em dois tipos. Application Interceptor (addInterceptor) executa entre o código da aplicação e o OkHttp: uma chamada chain.proceed() — uma requisição ao servidor, independentemente de redirecionamentos. Network Interceptor (addNetworkInterceptor) executa dentro do OkHttp após a formação de cabeçalhos e conexão — é acionado em cada redirecionamento, repetição ou tentativa de autenticação. Essa distinção é crítica para escolher o tipo correto de interceptador para uma tarefa 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} in ${duration}ms")
        return response
    }
}

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

LoggingInterceptor — um Application Interceptor que registra o método, URL, código de resposta e tempo de execução. Adicioná-lo via addInterceptor() garante um log por requisição do usuário sem duplicação em redirecionamentos. CacheInterceptor é adicionado como Network Interceptor para considerar os cabeçalhos Cache-Control do servidor, que só são visíveis dentro do OkHttp após a formação da requisição HTTP.

Diferença entre os tipos na prática

Quando a aplicação faz uma requisição, o servidor pode responder com um redirecionamento 302 ou 301. Application Interceptor vê apenas a resposta final após todos os redirecionamentos — ele não sabe quantas requisições intermediárias foram feitas. Network Interceptor vê cada requisição e resposta, incluindo as intermediárias. De acordo com Square (2026), o Network Interceptor também vê dados comprimidos no nível da conexão (gzip), enquanto o Application Interceptor recebe a resposta já descomprimida. Para contar o número real de chamadas de rede, use Network Interceptor.

Alamofire RequestInterceptor

Alamofire fornece o protocolo RequestInterceptor, que combina dois protocolos: RequestAdapter para modificar a requisição antes do envio e RequestRetrier para tentativas de repetição em erros. Essa separação permite combinar flexivelmente adaptação (adicionar cabeçalhos, tokens) com política de repetição (backoff exponencial, limite de tentativas, verificação de tipo de erro). O RequestInterceptor é implementado por uma única estrutura ou classe que está em conformidade com ambos os 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 em Swift adiciona um token Bearer através de adapt e repete automaticamente a requisição em caso de URLError (perda de rede, timeout) via retry com um atraso de 1 segundo. Separar adaptação e repetições permite testá-los independentemente — você pode escrever um teste unitário para adaptação sem afetar a lógica de repetição. De acordo com Alamofire (2026), o RequestInterceptor é a forma padrão de centralizar o gerenciamento de autenticação em projetos iOS.

Casos de uso de interceptadores

Logging — o caso de uso mais comum. O Interceptor registra a URL, método, cabeçalhos, corpo da requisição e resposta e tempo de execução. Em builds de depuração, isso substitui Charles Proxy e Wireshark; em builds de lançamento, ajuda relatórios de falhas com contexto da requisição. OkHttp usa HttpLoggingInterceptor da biblioteca logging-interceptor com níveis NONE, BASIC, HEADERS e BODY. O nível BODY registra corpos completos de requisições e respostas — use apenas em depuração.

Autenticação e renovação de token

Quando o token de acesso expira, o Interceptor intercepta a resposta 401, chama a API de renovação de token e repete a requisição original com o novo token. No OkHttp, isso é implementado via Authenticator ou um Interceptor personalizado com verificação de response.code. O Authenticator tem acesso apenas aos cabeçalhos da resposta, enquanto o Interceptor tem acesso ao corpo completo. No Alamofire — via RequestRetrier, retornando .retry após a renovação do token. De acordo com OWASP (2026), a renovação automática de tokens via Interceptor reduz o risco de vazamento de credenciais.

Adicionar cabeçalhos comuns

Content-Type, Accept-Language, User-Agent, Device-ID — cabeçalhos necessários em cada requisição. O Interceptor os adiciona centralizadamente, sem duplicação em cada método de API. User-Agent é formado uma vez na inicialização do aplicativo: “AppName/1.0 (Android 14; Pixel 8)”. Accept-Language é obtido do idioma do sistema do dispositivo. De acordo com Alamofire (2026), o gerenciamento centralizado de cabeçalhos via Interceptor reduz erros de cabeçalhos incorretos em 30%.

Melhores práticas e ordem da cadeia

A ordem de adição de Interceptors no OkHttp determina o comportamento de toda a cadeia. O primeiro interceptador adicionado executa primeiro ao enviar a requisição e último ao receber a resposta. Para logging, adicione o Interceptor primeiro — ele verá a requisição final com todas as modificações de outros interceptadores. Para compressão, adicione-o por último para que a compressão seja aplicada aos dados finais. Para autenticação, adicione-o antes da repetição para que o token seja renovado antes da próxima tentativa.

Recomendações para builds de produção

Em builds de lançamento, desative o logging via BuildConfig.DEBUG ou injeção de dependência. Use addNetworkInterceptor para cache — o Network Interceptor vê os cabeçalhos Cache-Control do servidor e interpreta corretamente a política de cache. Para autenticação, use addInterceptor (Application) — isso evita a reinterceptação em redirecionamentos para domínios de terceiros onde cabeçalhos de autorização não devem ser enviados. Teste cada Interceptor isoladamente usando MockWebServer do okhttp-testing-support — ele intercepta requisições e retorna respostas pré-preparadas, permitindo verificar a lógica do interceptador sem um servidor real.

Desempenho do Interceptor

Cada Interceptor adiciona um pequeno atraso ao tempo de requisição. Em uma cadeia típica de 3-4 interceptadores (logging, autenticação, compressão, cache), a sobrecarga é inferior a 5 milissegundos por requisição. Problemas surgem quando um Interceptor realiza operações bloqueantes: chamada síncrona à API de renovação de token, gravação de logs grandes em arquivo ou criptografia do corpo da requisição. Todas essas operações devem ser assíncronas ou executadas em uma thread em segundo plano. De acordo com Square (2026), OkHttp executa Interceptors no pool de threads Dispatcher — bloquear um interceptador atrasa toda a cadeia.

• Ordem importa — logging primeiro, autenticação antes da repetição, compressão por último
• Debug vs Release — HttpLoggingInterceptor apenas em builds de depuração
• Isolamento — cada Interceptor lida com uma tarefa (Responsabilidade Única)
• Assincronicidade — Interceptor executa na thread de fundo do OkHttp, sem bloquear a UI