Manuel d'utilisation d'ApiCatcher

ApiCatcher est un outil professionnel de débogage réseau iOS conçu pour les développeurs, les ingénieurs de test et le personnel de dépannage réseau. En établissant une passerelle virtuelle locale, il vous aide à capturer, visualiser, analyser et déboguer de manière pratique le trafic HTTP/HTTPS et WebSocket des applications que vous développez.

Ce manuel détaillera comment configurer et utiliser chaque module de fonctionnalités pour vous aider dans votre débogage de développement quotidien, vos tests Mock, votre analyse d'API automatisée et votre dépannage des performances.

Table des matières

Préparation de base : Configuration du certificat et autorisation de débogage
Filtrage du trafic : Ciblage précis des objectifs de débogage
Mocking et modification d'API : Règles de réécriture (Rewrite)
Traitement personnalisé avancé : Scripts JavaScript (Script)
Tests automatisés : Rejeu combiné (Combo Replay)
Surveillance en arrière-plan : Tâches planifiées (Scheduled Tasks)
Dépannage de la qualité et des performances : Analyse d'API (API Scan)
Outils utilitaires : Chiffrement/Déchiffrement et synchronisation de bureau

1. Préparation de base : Configuration du certificat et autorisation de débogage

1.1 Installer et faire confiance au certificat CA (Requis pour le débogage HTTPS)

L'interaction des données dans les applications modernes est généralement chiffrée sur la base du protocole HTTPS. Lors du développement et du débogage de vos propres applications, afin de visualiser correctement les requêtes en texte clair et les données de réponse des API, vous devez configurer et faire confiance à un certificat de débogage pour permettre le déchiffrement.

ApiCatcher offre deux façons de configurer les certificats :

Utiliser le certificat CA généré par défaut par le système (Recommandé pour la plupart des scénarios) : Suivez le guide ci-dessous pour installer le certificat CA exclusif généré automatiquement pour vous par ApiCatcher.
Importer votre propre certificat (Certificat d'entreprise) : Si vous devez utiliser un certificat auto-signé par l'entreprise, vous pouvez ignorer cette section directement et lire la section 1.2 Importation de certificat d'entreprise.

Étapes pour utiliser le certificat CA par défaut :

Cliquez sur "Installer le certificat" dans l'application, et le système basculera sur le navigateur pour télécharger le profil de configuration.
Accédez à "Paramètres" -> "Général" -> "VPN et gestion des appareils" d'iOS, et installez le profil ApiCatcher téléchargé.
Étape cruciale : Accédez à "Paramètres" -> "Général" -> "Informations" -> "Réglages de confiance des certificats", recherchez le certificat commençant par ApiCatcher CA et activez le commutateur pour activer la confiance totale.

💡 Guide de dépannage courant :

Obtention d'un "Délai de connexion dépassé" ou de codes d'état anormaux lors du débogage : Généralement parce que le certificat n'est pas "totalement approuvé" à l'étape 3.

Suppression de l'application et réinstallation : L'ancien certificat de débogage est désormais invalide. Vous devez vous rendre dans les paramètres du système pour supprimer l'ancien profil et répéter le processus ci-dessus à nouveau.

1.2 Importation de certificat d'entreprise (Scénario de débogage de l'intranet de l'entreprise)

Lors du développement et des tests internes de l'entreprise, certaines applications internes peuvent configurer des politiques de confiance de certificats spécifiques (par exemple, faire uniquement confiance à la CA interne de l'entreprise).

Utilisation : Importez le certificat .pem ou .p12 fourni par l'entreprise, et liez-le avec le domaine de test interne (par exemple, *.corp.internal), pour effectuer des négociations TLS légitimes lors du débogage local.
Remarque : L'importation ou la modification des configurations doit être effectuée pendant que la capture est arrêtée, et un redémarrage est nécessaire pour que les modifications prennent effet.

1.3 Utilisation de certificats personnalisés

Pour les développeurs indépendants qui ne disposent pas d'un certificat d'entreprise et ne souhaitent pas utiliser les certificats par défaut d'ApiCatcher, vous pouvez utiliser la fonctionnalité de Certificat d'Entreprise pour importer vos propres certificats. Pour plus de détails, veuillez consulter la documentation : Utilisation de certificats personnalisés

2. Filtrage du trafic : Ciblage précis des objectifs de débogage

Au cours du processus de développement, afin d'éliminer les interférences de trafic provenant du système sous-jacent et d'autres applications en arrière-plan, il est recommandé de configurer des règles de filtrage pour concentrer votre attention sur le projet en cours de débogage.

Liste de blocage (Blocklist) : Les domaines apparaissant dans la liste de blocage ne seront pas enregistrés. Si la liste d'autorisation est vide, toutes les requêtes à l'exception de celles de la liste de blocage sont enregistrées par défaut.
Liste d'autorisation (Allowlist) : Tant qu'il y a des règles dans la liste d'autorisation, le système enregistrera uniquement les requêtes correspondant à la liste d'autorisation, et tout le reste du trafic n'entrera pas dans le canal de débogage.
Conseils de configuration : Prend en charge le caractère générique *. Par exemple, la saisie de *.example-api.com peut correspondre à tous les sous-domaines de l'environnement de test sous ce domaine principal.

💡 Guide de dépannage courant :

Impossible de voir les requêtes de l'application cible : Veuillez vérifier si la liste d'autorisation est activée mais que le domaine cible a été oublié, ou si le domaine cible a été ajouté par erreur à la liste de blocage.

Remarque sur la syntaxe : Veuillez utiliser la correspondance d'astérisque de base (par exemple, *.api.com) ; il n'est pas nécessaire d'écrire des expressions régulières complexes.

3. Mocking et modification d'API : Règles de réécriture (Rewrite)

Lors du développement parallèle du front-end et du back-end, les API back-end ne sont souvent pas encore prêtes, ou vous devez tester certains codes d'état anormaux. Grâce aux règles de réécriture, vous pouvez effectuer des tests Mock d'API et des tests de limites de manière élégante.

3.1 Configuration de la portée (Scope)

Lors de l'ajout d'une règle de réécriture, vous devez spécifier la portée dans laquelle la règle prend effet pour éviter d'affecter accidentellement des requêtes non liées. Le système fournit une méthode de configuration extrêmement simple et vous n'avez pas besoin d'écrire de conditions de correspondance complexes :

Sélectionner le domaine/hôte (Host) : Vous pouvez sélectionner rapidement dans une liste déroulante d'hôtes cibles qui ont déjà été capturés, ou le saisir manuellement. Les caractères génériques sont pris en charge (par exemple, *.example.com).
Sélectionner l'API (Path) : Après avoir sélectionné l'hôte, vous pouvez sélectionner directement des API spécifiques dans la liste (la méthode et le chemin d'accès seront introduits automatiquement), ou saisir manuellement des chemins spécifiques (prend en charge la correspondance de chemin d'accès avec caractère générique *, par exemple, /api/v1/*).

💡 Conseil d'efficacité : Si vous sélectionnez une API existante dans la liste, le système pré-remplira (Prefill) automatiquement les modèles de réponse Mock ultérieurs ou Headers pour vous, ce qui vous fera gagner beaucoup de temps de configuration !

3.2 Actions de débogage (Rewrite Action)

Rediriger (Redirect) : Acheminer la requête vers une autre adresse (par exemple, rediriger le trafic de production vers Localhost ou un environnement de pré-production).
Réponse Mock : Ne pas envoyer de véritable requête réseau, renvoyer directement vos données de test prédéfinies (JSON/XML). Prend en charge la configuration des codes d'état (par exemple, simulation d'exceptions 404, 500), des en-têtes de réponse et des corps de réponse.
Ignorer (Drop) :
- Ignorer la requête : Simuler une requête qui ne peut pas être envoyée (par exemple, scénario de déconnexion réseau).
- Ignorer la réponse : Simuler l'absence de réponse/délai d'attente du serveur.
Délai (Delay) : Injecter un délai réseau artificiellement, utilisé pour tester les performances d'interaction Loading de l'application dans des environnements de réseau faibles.
Modifier la requête/réponse (Modify) :
- Modifier l'en-tête : Utilisé pour injecter des jetons de test dans les en-têtes de requête ou modifier l'User-Agent.
- Remplacer le corps (Body) : Remplacer complètement le contenu du corps de la requête ou du corps de la réponse.
- Rechercher et remplacer le corps avec une expression régulière (Regex) : Effectuer un remplacement de champ à granularité fine sur JSON. Par exemple, utilisez l'expression régulière pour remplacer "status": "pending" par "status": "success" pour tester la logique ultérieure.

💡 Guide de dépannage courant :

La règle ne prend pas effet : Il existe une autre règle avec une priorité plus élevée (ajoutée récemment) qui annule la règle actuelle.

Le remplacement de l'expression régulière échoue : Les données JSON contiennent souvent des retraits et des espaces. Si l'expression régulière ne tient pas compte des caractères d'espacement (par exemple, en utilisant \s*), la correspondance peut échouer. Il est recommandé d'utiliser le panneau "Test" intégré pour vérifier l'expression.

4. Traitement personnalisé avancé : Scripts JavaScript (Script)

Pour les scénarios Mock complexes nécessitant un calcul dynamique (comme le calcul de signature d'horodatage, l'assemblage de données dynamiques), le moteur de script fournit le plus haut niveau de capacités de débogage programmables.

4.1 Panneaux de fonctions de base et outils auxiliaires

En plus du codage manuel, ApiCatcher fournit de puissants outils environnants pour vous aider à terminer la création et la vérification de scripts :

Générer automatiquement des scripts avec l'IA : Pas besoin d'écrire une seule ligne de code à la main. Il vous suffit de saisir des instructions en langage naturel (par exemple : "Aidez-moi à changer la valeur du champ price dans le corps de la réponse à 9.9, et à ajouter discount_tag: true"), et l'assistant IA intégré peut générer et remplir directement le code JS standard pour vous.
Environnement de test local (Test Script) : Avant d'enregistrer officiellement pour que cela prenne effet, vous pouvez cliquer directement pour tester. Vous pouvez choisir une requête réellement capturée dans l'historique pour l'alimenter au script, et le système affichera intuitivement les résultats de comparaison de données avant et après la modification ainsi que tous les journaux d'erreurs, garantissant que votre syntaxe est correcte.
Hébergement de scripts distant (Remote Script) : Prend en charge la saisie directe d'une URL de script http:// ou https:// publique. ApiCatcher chargera et exécutera localement le script cloud, ce qui est très utile pour déployer et maintenir de manière uniforme des règles Mock publiques au sein d'une équipe !

4.2 Fonctions principales du script

Pour savoir comment écrire des scripts, veuillez lire la documentation : Guide d'utilisation de la fonction de script APICatcher

Vous n'avez besoin d'implémenter que des fonctions de cycle de vie prédéfinies :

// Traiter les requêtes sortantes
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // Actions de retour : passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

// Traiter les réponses reçues
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // Fonction d'analyse sûre intégrée
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 API avancées intégrées

localStore : Utilisé pour la maintenance de l'état sur plusieurs requêtes. Par exemple, enregistrer l'état d'autorisation dans l'API de connexion et l'injecter automatiquement dans les API suivantes.
- localStore.write('session_id', 'abc')
- var t = localStore.read('session_id')
httpClient : Prend en charge l'envoi de requêtes réseau supplémentaires pendant l'exécution du script (utilisé pour synchroniser les états externes ou récupérer des configurations dynamiques).
- var res = httpClient.get('https://api.ipify.org')

💡 Guide de dépannage courant :

Erreurs de syntaxe ou d'exécution : Utilisez le bouton "Script de test" intégré pour vérifier la logique. Vous pouvez utiliser console.log("...") et afficher la sortie sur la page "Journaux (Logs)".

Conflits de cycle de vie : Si une requête a déjà été Mocked ou Dropped par une "Règle de réécriture" de priorité supérieure, elle n'entrera plus dans le flux d'exécution de script ultérieur pour cette requête.

5. Tests automatisés : Rejeu combiné (Combo Replay)

Tester une seule API ne peut pas satisfaire la vérification du flux commercial complet (par exemple : Connexion -> Obtenir l'autorisation -> Interroger les informations -> Soumettre le formulaire). Combo Replay prend en charge l'orchestration visuelle et la régression automatisée de plusieurs API associées.

5.1 Étapes de configuration

Ajouter des nœuds : Ajoutez séquentiellement des requêtes de flux d'activité de l'historique à la zone de dessin.
Établir des dépendances : Créez des arêtes dirigées entre les nœuds pour garantir que les requêtes sont exécutées de manière strictement séquentielle en fonction de leurs dépendances.
Mappage de paramètres (Injection de dépendance) : Configurer le flux de données. Injectez dynamiquement des champs spécifiques à partir de la réponse d'une API en amont dans des requêtes en aval.

5.2 Détails de la configuration du mappage des paramètres

Source d'extraction : Peut être extrait du responseBody ou du responseHeader en amont.
- Chemin d'extraction : S'il s'agit d'un corps de réponse JSON, utilisez directement JSON Path (par exemple, data.session.token).
Cible d'injection : Peut être injecté dans le requestHeader, le queryParam ou le requestBody en aval.
Préfixe facultatif (Optional Prefix) : Utilisé pour l'auto-complétion de normes spécifiques. Par exemple, si la valeur extraite est abc, mais que la norme exige l'envoi de Bearer abc dans l'en-tête, remplissez simplement Bearer ici pour le concaténer automatiquement.

💡 Guide de dépannage courant :

Paramètre non extrait avec succès : Utilisez l'arborescence du "Corps de réponse d'échantillon" intégrée au nœud de canevas pour cliquer et sélectionner, évitant ainsi les erreurs de hiérarchie de format causées par l'écriture manuelle du chemin.

6. Exécution en arrière-plan : Tâches planifiées (Scheduled Tasks)

Avec la capacité de résidence en arrière-plan basée sur le processus VPN, vous pouvez utiliser des "Tâches planifiées" pour exécuter périodiquement des requêtes spécifiques ou des règles de rejeu combiné. Scénario d'application typique : Lors du développement ou du test d'un événement de "vente flash" e-commerce, étant donné que la fenêtre de temps de la vente flash est extrêmement courte, le clic manuel manque souvent le moment exact. À ce moment, vous pouvez configurer une tâche planifiée pour laisser l'API demander automatiquement la soumission de la commande à haute fréquence juste avant le début de la vente flash, vous aidant à vérifier pleinement la stabilité de la concurrence et la logique métier du lien de la vente flash.

6.1 Configuration de la planification (Schedule Type)

Expression Cron : Utilise la syntaxe Cron standard à 5 champs (par exemple, */5 * * * * signifie exécuter toutes les 5 minutes). Vous pouvez utiliser l'assistance IA intégrée pour la générer.
Configuration personnalisée : Prend en charge un réglage précis de l'heure de début, de la durée de l'intervalle et du nombre maximal d'exécutions.

6.2 Conditions d'arrêt automatique (Auto Terminate)

Définissez des conditions d'arrêt pour éviter des tentatives dénuées de sens dans des situations anormales, ou pour quitter automatiquement après avoir atteint l'objectif :

Correspondance de champs JSON : Par exemple, dans le scénario de "test de vente flash", surveillez le champ code du résultat renvoyé. Une fois que code est égal à 200 (signifiant la soumission d'achat réussie) ou égal à 400 (signifiant l'inventaire vide et l'événement terminé), la fin est déclenchée.
Correspondance d'expression régulière : Effectuez une correspondance en texte intégral sur le corps de la réponse. Tant que les signatures de caractères comme "msg": "Achat réussi" ou "error": "L'événement est terminé" correspondent, la tâche s'arrêtera automatiquement complètement.

💡 Guide de dépannage courant :

La tâche ne peut pas s'exécuter : Le système iOS dispose de contrôles stricts en arrière-plan. Lorsque la mémoire est saturée, le processus VPN peut être récupéré par le système, et les tâches planifiées s'interrompront avec lui.

Aucun historique affiché : Les tâches planifiées surveillent les requêtes initiées directement par le moteur sous-jacent et ne seront pas enregistrées dans l'"Historique" régulier de l'application principale. Vous devez afficher des rapports tels que le taux de réussite et le p95 dans le panneau "Historique d'exécution" exclusif à la tâche.

Les mises à jour des règles ne prennent pas effet : Les tâches planifiées sont liées à un instantané de la règle au moment de leur création. Si la règle "Combo Replay" d'origine est modifiée, la tâche planifiée doit être recréée.

7. Dépannage de la qualité et des performances : Analyse d'API (API Scan)

Sur la base des enregistrements de trafic capturés localement, il fournit des contrôles de santé non intrusifs sur la qualité, la conformité de la sécurité et les performances des API. Toutes les analyses sont effectuées entièrement dans la boucle de mémoire locale de l'appareil.

7.1 Moteur d'analyse intégré

Auto-vérification des informations sensibles : Prend en charge la détection des transmissions en texte clair des numéros de téléphone, des cartes d'identité, des e-mails et des identifiants des services cloud (tels que les clés AWS, les clés API OpenAI), aidant les concepteurs front-end et d'API à découvrir précocement les omissions de désensibilisation des données.
Fuite anormale de pile : Identifie les piles d'appels d'erreurs Java, Python ou SQL renvoyées par inadvertance dans les corps de réponse.
Analyse des appels à haute fréquence : En fonction des seuils définis (par exemple, un intervalle de requête moyen inférieur à un certain nombre de millisecondes), vérifie s'il existe des appels d'API redondants causés par des boucles infinies ou une logique incorrecte.
Évaluation du temps de consommation : Agrège et calcule les latences p95 et p99 pour diverses API, aidant à localiser les goulots d'étranglement des performances backend.

7.2 Détection de qualité personnalisée (Custom Scan)

Vous pouvez écrire des scripts JS pour exécuter des vérifications de conformité personnalisées en fonction des besoins de l'entreprise.

Convention de la valeur de retour : Si la fonction estime que la requête répond aux attentes, elle renvoie null ; si une non-conformité est détectée (par exemple, un corps de réponse trop grand, des en-têtes de sécurité manquants), renvoyez une description concise (≤200 caractères) et le système l'inclura automatiquement dans le rapport d'analyse.

💡 Guide de dépannage courant :

Aucun résultat n'a été analysé : Confirmez si la "Portée de l'analyse (Host/Session)" contient réellement des enregistrements de trafic JSON/API valides, plutôt que des ressources purement statiques. Afin de garantir une bonne expérience, il existe une limite maximale d'enregistrements pour une seule analyse.

8. Outils utilitaires : Chiffrement/Déchiffrement et synchronisation de bureau

8.1 Boîte à outils du développeur (Decrypt/Encrypt)

Pour faire face aux transmissions de charge utile chiffrées, des outils de codec courants sont intégrés :

Déchiffrement AES : Prend en charge la saisie de clés (Key) et de vecteurs d'initialisation (IV) personnalisés pour déchiffrer et tester rapidement les charges utiles (Payloads).
Base64 / URL Encode / MD5 / SHA256.
Traitement personnalisé : Prend en charge l'écriture d'extraits JS à exécution unique pour effectuer une transformation de données sur le texte sélectionné.

8.2 Synchronisation en temps réel sur le bureau (Realtime Sync)

Utilisation : Si vous avez besoin de déboguer des données avec une vue plus large sur un PC, vous pouvez envoyer de manière transparente les paquets de données capturés par l'appareil à l'application de bureau ApiCatcher Desktop via le protocole WebSocket. Configuration :

Entrez l'adresse WebSocket allouée dans le réseau local.
Assurez-vous de passer le "Test de connectivité" en premier pour vérifier la réussite de la prise de contact.
Dépannage : Assurez-vous que le terminal mobile a reçu l'autorisation "Réseau local", que le pare-feu du PC a autorisé le port correspondant et assurez-vous que les deux se trouvent sur le même sous-réseau LAN.