Interceptor — ce que c’est, types d’intercepteurs OkHttp et Alamofire

Qu’est-ce qu’un Interceptor ?

Interceptor est un composant logiciel injecté dans un client HTTP pour intercepter et modifier les requêtes avant leur envoi au serveur et les réponses avant qu’elles n’atteignent l’application. En développement mobile, les intercepteurs gèrent des préoccupations transversales : injection automatique de jetons d’authentification, journalisation du trafic avec mesures de temps, tentatives en cas d’erreurs réseau temporaires, compression et déchiffrement des données à la volée. L’architecture Interceptor est basée sur le modèle Chain of Responsibility — chaque intercepteur peut modifier la requête, l’exécuter ou interrompre la chaîne en renvoyant une réponse personnalisée.

Comment fonctionne la chaîne d’intercepteurs

Dans OkHttp, les intercepteurs forment une chaîne. Chaque Interceptor reçoit un objet Chain avec la requête d’origine et appelle chain.proceed(request) pour passer le contrôle à l’intercepteur suivant. Après avoir reçu la réponse, l’intercepteur peut analyser la Response, la modifier, réessayer la requête en cas d’erreur ou renvoyer une réponse personnalisée pour la mise en cache. L’ordre d’ajout des intercepteurs à OkHttpClient.Builder détermine leur ordre d’exécution : le premier ajouté s’exécute en premier à l’envoi et en dernier à la réception.

Interceptor dans OkHttp : Application et Network

OkHttp sépare les intercepteurs en deux types. Application Interceptor (addInterceptor) s’exécute entre le code de l’application et OkHttp : un appel chain.proceed() — une requête au serveur, indépendamment des redirections. Network Interceptor (addNetworkInterceptor) s’exécute à l’intérieur d’OkHttp après la formation des en-têtes et la connexion — il se déclenche à chaque redirection, tentative ou authentification. Cette distinction est essentielle pour choisir le bon type d’intercepteur pour une tâche spécifique.

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 — un Application Interceptor qui enregistre la méthode, l’URL, le code de réponse et le temps d’exécution. L’ajouter via addInterceptor() garantit un journal par requête utilisateur sans duplication lors des redirections. CacheInterceptor est ajouté comme Network Interceptor pour prendre en compte les en-têtes Cache-Control du serveur, qui ne sont visibles qu’à l’intérieur d’OkHttp après la formation de la requête HTTP.

Différence entre les types en pratique

Lorsque l’application effectue une requête, le serveur peut répondre par une redirection 302 ou 301. Application Interceptor ne voit que la réponse finale après toutes les redirections — il ne sait pas combien de requêtes intermédiaires ont été effectuées. Network Interceptor voit chaque requête et réponse, y compris les intermédiaires. Selon Square (2026), Network Interceptor voit également les données compressées au niveau de la connexion (gzip), alors qu’Application Interceptor reçoit la réponse déjà décompressée. Pour compter le nombre réel d’appels réseau, utilisez Network Interceptor.

Alamofire RequestInterceptor

Alamofire fournit le protocole RequestInterceptor, qui combine deux protocoles : RequestAdapter pour modifier la requête avant l’envoi et RequestRetrier pour les tentatives en cas d’erreur. Cette séparation permet de combiner flexibilité l’adaptation (ajout d’en-têtes, de jetons) avec la politique de tentatives (backoff exponentiel, limite de tentatives, vérification du type d’erreur). RequestInterceptor est implémenté par une seule structure ou classe qui se conforme aux deux protocoles.

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 ajoute un jeton Bearer via adapt et réessaye automatiquement la requête en cas d’URLError (perte de réseau, délai d’attente) via retry avec un délai d’une seconde. Séparer l’adaptation et les tentatives permet de les tester indépendamment — vous pouvez écrire un test unitaire pour l’adaptation sans affecter la logique de tentative. Selon Alamofire (2026), RequestInterceptor est la méthode standard pour centraliser la gestion de l’authentification dans les projets iOS.

Cas d’utilisation des intercepteurs

Journalisation — le cas d’utilisation le plus courant. L’Interceptor enregistre l’URL, la méthode, les en-têtes, le corps de la requête et de la réponse ainsi que le temps d’exécution. Dans les versions de débogage, cela remplace Charles Proxy et Wireshark ; dans les versions de production, cela aide les rapports d’incident avec le contexte de la requête. OkHttp utilise HttpLoggingInterceptor de la bibliothèque logging-interceptor avec les niveaux NONE, BASIC, HEADERS et BODY. Le niveau BODY enregistre les corps complets des requêtes et réponses — à utiliser uniquement en débogage.

Authentification et renouvellement de jeton

Lorsque le jeton d’accès expire, l’Interceptor intercepte la réponse 401, appelle l’API de renouvellement de jeton et réessaye la requête d’origine avec le nouveau jeton. Dans OkHttp, cela est implémenté via Authenticator ou un Interceptor personnalisé avec vérification de response.code. L’Authenticator n’a accès qu’aux en-têtes de réponse, tandis que l’Interceptor a accès au corps complet. Dans Alamofire — via RequestRetrier, retournant .retry après le renouvellement du jeton. Selon OWASP (2026), le renouvellement automatique des jetons via Interceptor réduit le risque de fuite d’informations d’identification.

Ajout d’en-têtes communs

Content-Type, Accept-Language, User-Agent, Device-ID — des en-têtes requis dans chaque requête. L’Interceptor les ajoute de manière centralisée, sans duplication dans chaque méthode API. User-Agent est formé une fois au démarrage de l’application : « AppName/1.0 (Android 14 ; Pixel 8) ». Accept-Language est tiré de la langue système de l’appareil. Selon Alamofire (2026), la gestion centralisée des en-têtes via Interceptor réduit les erreurs d’en-têtes incorrects de 30 %.

Bonnes pratiques et ordre de la chaîne

L’ordre d’ajout des Interceptors dans OkHttp détermine le comportement de toute la chaîne. Le premier intercepteur ajouté s’exécute en premier à l’envoi de la requête et en dernier à la réception de la réponse. Pour la journalisation, ajoutez l’Interceptor en premier — il verra la requête finale avec toutes les modifications des autres intercepteurs. Pour la compression, ajoutez-le en dernier pour que la compression soit appliquée aux données finales. Pour l’authentification, ajoutez-le avant la tentative pour que le jeton soit renouvelé avant la prochaine tentative.

Recommandations pour les versions de production

Dans les versions de production, désactivez la journalisation via BuildConfig.DEBUG ou l’injection de dépendances. Utilisez addNetworkInterceptor pour la mise en cache — Network Interceptor voit les en-têtes Cache-Control du serveur et interprète correctement la politique de cache. Pour l’authentification, utilisez addInterceptor (Application) — cela évite la réinterception lors des redirections vers des domaines tiers où les en-têtes d’autorisation ne doivent pas être envoyés. Testez chaque Interceptor isolément avec MockWebServer d’okhttp-testing-support — il intercepte les requêtes et renvoie des réponses préparées, vous permettant de vérifier la logique d’intercepteur sans serveur réel.

Performances de l’Interceptor

Chaque Interceptor ajoute un petit retard au temps de requête. Dans une chaîne typique de 3-4 intercepteurs (journalisation, authentification, compression, cache), la surcharge est inférieure à 5 millisecondes par requête. Des problèmes surviennent lorsqu’un Interceptor effectue des opérations bloquantes : appel synchrone à l’API de renouvellement de jeton, écriture de gros journaux dans un fichier ou chiffrement du corps de la requête. Toutes ces opérations doivent être asynchrones ou exécutées dans un thread d’arrière-plan. Selon Square (2026), OkHttp exécute les Interceptors dans le pool de threads Dispatcher — bloquer un intercepteur retarde toute la chaîne.

• L’ordre compte — journalisation en premier, authentification avant tentative, compression en dernier
• Débogage vs Production — HttpLoggingInterceptor uniquement dans les versions de débogage
• Isolation — chaque Interceptor gère une tâche (Responsabilité Unique)
• Asynchronisme — Interceptor s’exécute dans le thread d’arrière-plan d’OkHttp, sans bloquer l’interface