ApiCatcher Benutzerhandbuch

ApiCatcher ist ein professionelles iOS-Netzwerk-Debugging-Tool für Entwickler, Testingenieure und Netzwerk-Fehlerbeheber. Durch die Einrichtung eines lokalen virtuellen Gateways können Sie den HTTP/HTTPS- und WebSocket-Verkehr der von Ihnen entwickelten Anwendungen bequem erfassen, anzeigen, analysieren und debuggen.

Dieses Handbuch beschreibt detailliert, wie Sie jedes Funktionsmodul konfigurieren und verwenden können, um Sie bei Ihrem täglichen Entwicklungs-Debugging, Mock-Tests, der automatisierten API-Analyse und der Leistungsfehlerbehebung zu unterstützen.

Inhaltsverzeichnis

Grundvorbereitung: Zertifikatskonfiguration & Debug-Autorisierung
Verkehrsfilterung: Präzise Ausrichtung auf Debugging-Ziele
API-Mocking & Änderung: Umschreibregeln (Rewrite)
Erweiterte benutzerdefinierte Verarbeitung: JavaScript-Skripte (Script)
Automatisiertes Testen: Combo-Replay
Hintergrundüberwachung: Geplante Aufgaben (Scheduled Tasks)
Fehlerbehebung bei Qualität und Leistung: API-Scan
Dienstprogramme: Verschlüsselung/Entschlüsselung & Desktop-Synchronisierung

1. Grundvorbereitung: Zertifikatskonfiguration & Debug-Autorisierung

1.1 CA-Zertifikat installieren und vertrauen (Erforderlich für HTTPS-Debugging)

Die Dateninteraktion in modernen Anwendungen wird im Allgemeinen basierend auf dem HTTPS-Protokoll verschlüsselt. Wenn Sie Ihre eigenen Anwendungen entwickeln und debuggen, müssen Sie ein Debugging-Zertifikat konfigurieren und diesem vertrauen, um die Entschlüsselung zu ermöglichen, damit Sie die Klartextanforderungs- und Antwortdaten der APIs ordnungsgemäß anzeigen können.

ApiCatcher bietet zwei Möglichkeiten zum Konfigurieren von Zertifikaten:

Verwenden Sie das vom System standardmäßig generierte CA-Zertifikat (Empfohlen für die meisten Szenarien): Befolgen Sie die nachstehende Anleitung, um das exklusive CA-Zertifikat zu installieren, das ApiCatcher automatisch für Sie generiert.
Importieren Sie Ihr eigenes Zertifikat (Unternehmenszertifikat): Wenn Sie ein vom Unternehmen selbst signiertes Zertifikat verwenden müssen, können Sie diesen Abschnitt direkt überspringen und den Abschnitt 1.2 Importieren von Unternehmenszertifikaten lesen.

Schritte zur Verwendung des Standard-CA-Zertifikats:

Klicken Sie in der App auf "Zertifikat installieren", und das System springt in den Browser, um das Konfigurationsprofil herunterzuladen.
Gehen Sie zu iOS "Einstellungen" -> "Allgemein" -> "VPN und Geräteverwaltung" und installieren Sie das heruntergeladene ApiCatcher-Profil.
Wichtiger Schritt: Gehen Sie zu "Einstellungen" -> "Allgemein" -> "Info" -> "Zertifikatsvertrauenseinstellungen", suchen Sie das Zertifikat, das mit ApiCatcher CA beginnt, und schalten Sie den Schalter ein, um volles Vertrauen zu ermöglichen.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Abrufen von "Verbindungs-Timeout" oder abnormale Statuscodes während des Debuggens: Meistens, weil das Zertifikat in Schritt 3 nicht "vollständig vertrauenswürdig" ist.

Die App gelöscht und neu installiert: Das alte Debugging-Zertifikat ist jetzt ungültig. Sie müssen in die Systemeinstellungen gehen, um das alte Profil zu entfernen und den obigen Vorgang erneut zu wiederholen.

1.2 Import von Unternehmenszertifikaten (Unternehmens-Intranet-Debugging-Szenario)

Während der internen Entwicklung und Tests im Unternehmen können einige interne Anwendungen spezifische Zertifikatsvertrauensrichtlinien (z. B. nur der internen Unternehmens-CA vertrauen) konfigurieren.

Verwendung: Importieren Sie das vom Unternehmen bereitgestellte .pem- oder .p12-Zertifikat und binden Sie es an die interne Testdomäne (z. B. *.corp.internal), um während des lokalen Debuggens legitime TLS-Handshakes abzuschließen.
Hinweis: Das Importieren oder Ändern von Konfigurationen muss bei gestoppter Erfassung erfolgen, und ein Neustart ist erforderlich, damit die Änderungen wirksam werden.

1.3 Verwendung benutzerdefinierter Zertifikate

Für einzelne Entwickler, die kein Enterprise-Zertifikat besitzen und die von ApiCatcher bereitgestellten Standardzertifikate nicht verwenden möchten, können Sie die Enterprise-Zertifikatsfunktion nutzen, um Ihre eigenen Zertifikate zu importieren. Weitere Details finden Sie in der Dokumentation: Verwendung benutzerdefinierter Zertifikate

2. Verkehrsfilterung: Präzise Ausrichtung auf Debugging-Ziele

Während des Entwicklungsprozesses wird empfohlen, Filterregeln zu konfigurieren, um Ihre Aufmerksamkeit auf das derzeit zu debuggende Projekt zu richten und Verkehrsstörungen durch das zugrunde liegende System und andere Hintergrund-Apps zu eliminieren.

Sperrliste (Blocklist): Domänen, die auf der Sperrliste stehen, werden nicht aufgezeichnet. Wenn die Zulassungsliste leer ist, werden standardmäßig alle Anfragen mit Ausnahme derer in der Sperrliste aufgezeichnet.
Zulassungsliste (Allowlist): Solange Regeln in der Zulassungsliste enthalten sind, wird das System nur Anfragen aufzeichnen, die mit der Zulassungsliste übereinstimmen, und der gesamte andere Verkehr wird nicht in den Debugging-Kanal eintreten.
Konfigurationstipps: Unterstützt das Platzhalterzeichen *. Die Eingabe von *.example-api.com kann beispielsweise mit allen Subdomänen der Testumgebung unter dieser Hauptdomäne übereinstimmen.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Die Anfragen der Ziel-App können nicht angezeigt werden: Überprüfen Sie, ob die Zulassungsliste aktiviert ist, aber die Zieldomäne übersehen wurde, oder ob die Zieldomäne fälschlicherweise zur Sperrliste hinzugefügt wurde.

Hinweis zur Syntax: Bitte verwenden Sie den grundlegenden Sternchenabgleich (z. B. *.api.com). Es müssen keine komplexen regulären Ausdrücke geschrieben werden.

3. API-Mocking & Änderung: Umschreibregeln (Rewrite)

Während der parallelen Entwicklung von Frontend und Backend sind Backend-APIs oft noch nicht bereit, oder Sie müssen bestimmte anormale Statuscodes testen. Durch Umschreibregeln können Sie API-Mocking und Grenzwerttests auf elegante Weise durchführen.

3.1 Bereichskonfiguration (Scope)

Wenn Sie eine Umschreibregel hinzufügen, müssen Sie den Bereich angeben, in dem die Regel wirksam wird, um versehentliche Auswirkungen auf nicht zusammenhängende Anforderungen zu vermeiden. Das System bietet eine äußerst einfache Konfigurationsmethode, und Sie müssen keine komplexen Übereinstimmungsbedingungen schreiben:

Domäne/Host auswählen (Host): Sie können schnell aus einer Dropdown-Liste von Ziel-Hosts auswählen, die bereits erfasst wurden, oder diese manuell eingeben. Platzhalter werden unterstützt (z. B. *.example.com).
API auswählen (Path): Nach Auswahl des Hosts können Sie bestimmte APIs direkt aus der Liste auswählen (Methode und Pfad werden automatisch eingefügt) oder bestimmte Pfade manuell eingeben (unterstützt Pfadabgleich mit Platzhalter *, z. B. /api/v1/*).

💡 Effizienz-Tipp: Wenn Sie eine vorhandene API aus der Liste auswählen, füllt das System die nachfolgenden Mock-Antwortvorlagen oder Headers automatisch für Sie aus (Prefill) und spart Ihnen so viel Konfigurationszeit!

3.2 Debugging-Aktionen (Rewrite Action)

Umleiten (Redirect): Leiten Sie die Anforderung an eine andere Adresse weiter (leiten Sie beispielsweise den Produktionsverkehr auf Localhost oder eine Staging-Umgebung um).
Mock-Antwort: Senden Sie keine tatsächliche Netzwerkanfrage, geben Sie Ihre voreingestellten Testdaten (JSON/XML) direkt zurück. Unterstützt die Konfiguration von Statuscodes (z. B. Simulation von 404, 500 Ausnahmen), Antwortheadern und Antworttexten.
Verwerfen (Drop):
- Anfrage verwerfen: Simulieren Sie eine Anfrage, die nicht gesendet werden kann (z. B. Netzwerk-Trennungs-Szenario).
- Antwort verwerfen: Simulieren Sie die Nichtreaktion/Zeitüberschreitung des Servers.
Verzögerung (Delay): Künstliches Einfügen von Netzwerkverzögerungen, die verwendet werden, um die Lade-Interaktionsleistung der App in schwachen Netzwerkumgebungen zu testen.
Anfrage/Antwort ändern (Modify):
- Header bearbeiten: Wird verwendet, um Test-Token in Anforderungsheader einzufügen oder den User-Agent zu ändern.
- Body ersetzen: Ersetzen Sie den Inhalt des Anforderungskörpers oder des Antwortkörpers vollständig.
- Regex Suchen und Ersetzen im Body: Führen Sie einen feingranularen Feldaustausch in JSON durch. Verwenden Sie beispielsweise einen regulären Ausdruck, um "status": "pending" durch "status": "success" zu ersetzen, um die nachfolgende Logik zu testen.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Regel wird nicht wirksam: Es gibt eine andere Regel mit höherer Priorität (kürzlich hinzugefügt), die die aktuelle Regel überschreibt.

Regex-Ersatz schlägt fehl: JSON-Daten enthalten häufig Einrückungen und Leerzeichen. Wenn der reguläre Ausdruck keine Leerzeichen berücksichtigt (z. B. mit \s*), kann die Übereinstimmung fehlschlagen. Es wird empfohlen, das integrierte "Test"-Fenster zu verwenden, um den Ausdruck zu überprüfen.

4. Erweiterte benutzerdefinierte Verarbeitung: JavaScript-Skripte (Script)

Für komplexe Mock-Szenarien, die dynamische Berechnungen erfordern (wie z.B. Zeitstempel-Signaturberechnung, dynamische Datenassemblierung), bietet die Skript-Engine die höchste Ebene der programmierbaren Debugging-Funktionen.

4.1 Kernfunktionsfelder und Hilfsmittel

Zusätzlich zur manuellen Codierung bietet ApiCatcher leistungsstarke Umgebungswerkzeuge, die Ihnen bei der Skripterstellung und -überprüfung helfen:

KI-Skripte automatisch generieren: Sie müssen keine einzige Codezeile von Hand schreiben. Sie müssen nur Anweisungen in natürlicher Sprache eingeben (z. B. „Hilf mir, den Wert des Feldes price im Antworttext auf 9.9 zu ändern und füge discount_tag: true hinzu“), und der integrierte KI-Assistent kann direkten Standard-JS-Code für Sie generieren und ausfüllen.
Lokale Testumgebung (Test Script): Bevor Sie offiziell speichern, um wirksam zu werden, können Sie direkt auf Testen klicken. Sie können eine tatsächlich erfasste Anforderung aus dem Verlauf auswählen, um sie dem Skript zuzuführen, und das System zeigt intuitiv die Datenvergleichsergebnisse vor und nach der Änderung zusammen mit Fehlerprotokollen an, um sicherzustellen, dass Ihre Syntax korrekt ist.
Remote Script Hosting (Remote Script): Unterstützt die direkte Eingabe einer öffentlichen http://- oder https://-Skript-URL. ApiCatcher lädt das Cloud-Skript lokal und führt es aus. Dies ist sehr hilfreich für die einheitliche Bereitstellung und Pflege öffentlicher Mock-Regeln innerhalb eines Teams!

4.2 Skript-Kernfunktionen

Informationen zum Schreiben von Skripten finden Sie in der Dokumentation: APICatcher Skript-Funktion Benutzerhandbuch

Sie müssen lediglich vordefinierte Lebenszyklusfunktionen implementieren:

// Ausgehende Anforderungen verarbeiten
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';
    }
    // Aktionen zurückgeben: passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

// Empfangene Antworten verarbeiten
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // Eingebaute sichere Parse-Funktion
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 Integrierte erweiterte APIs

localStore: Wird für die Statuserhaltung über Anforderungen hinweg verwendet. Zum Beispiel Speichern des Autorisierungsstatus in der Anmelde-API und automatisches Einfügen in nachfolgende APIs.
- localStore.write('session_id', 'abc')
- var t = localStore.read('session_id')
httpClient: Unterstützt das Senden zusätzlicher Netzwerkanfragen während der Skriptausführung (wird zum Synchronisieren externer Zustände oder zum Abrufen dynamischer Konfigurationen verwendet).
- var res = httpClient.get('https://api.ipify.org')

💡 Allgemeine Anleitung zur Fehlerbehebung:

Syntax- oder Laufzeitfehler: Verwenden Sie die integrierte Schaltfläche "Test Script", um die Logik zu überprüfen. Sie können console.log("...") verwenden und die Ausgabe auf der Seite "Protokolle (Logs)" anzeigen.

Lebenszykluskonflikte: Wenn eine Anfrage bereits durch eine "Umschreibregel" mit höherer Priorität "gemockt" oder "verworfen" wurde, wird sie für diese Anforderung nicht mehr in den nachfolgenden Skriptausführungsablauf eintreten.

5. Automatisiertes Testen: Combo-Replay

Das Testen einer einzelnen API reicht nicht aus, um den vollständigen Geschäftsablauf zu überprüfen (z. B.: Anmelden -> Autorisierung einholen -> Informationen abfragen -> Formular senden). Combo Replay unterstützt die visuelle Orchestrierung und automatisierte Regression mehrerer verbundener APIs.

5.1 Konfigurationsschritte

Knoten hinzufügen: Fügen Sie nacheinander Workflow-Anforderungen aus dem Verlauf zum Canvas hinzu.
Abhängigkeiten herstellen: Erstellen Sie gerichtete Kanten zwischen Knoten, um sicherzustellen, dass die Anforderungen in strikter Reihenfolge gemäß ihren Abhängigkeiten ausgeführt werden.
Parameterzuordnung (Abhängigkeitsinjektion): Datenfluss konfigurieren. Fügen Sie bestimmte Felder aus der Antwort einer vorgelagerten API dynamisch in nachgelagerte Anforderungen ein.

5.2 Details zur Parameterzuordnungskonfiguration

Extraktionsquelle: Kann aus dem vorgelagerten responseBody oder responseHeader extrahiert werden.
- Extraktionspfad: Wenn es sich um einen JSON-Antworttext handelt, verwenden Sie JSON Path direkt (z. B. data.session.token).
Injektionsziel: Kann in den nachgelagerten requestHeader, queryParam oder requestBody eingefügt werden.
Optionales Präfix (Optional Prefix): Wird zur automatischen Vervollständigung bestimmter Standards verwendet. Wenn der extrahierte Wert beispielsweise abc ist, die Norm jedoch verlangt, dass Bearer abc im Header gesendet wird, füllen Sie hier einfach Bearer aus, um es automatisch zu verketten.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Parameter wurde nicht erfolgreich extrahiert: Verwenden Sie die Baumstruktur des "Beispiel-Antworttexts", die in den Canvas-Knoten integriert ist, zum Klicken und Auswählen. Dadurch werden Formathierarchiefehler vermieden, die durch manuelles Schreiben von Pfaden verursacht werden.

6. Hintergrundausführung: Geplante Aufgaben (Scheduled Tasks)

Mit der VPN-prozessbasierten Hintergrundresidenzfunktion können Sie mithilfe von "Geplanten Aufgaben" regelmäßig bestimmte Anforderungen oder Combo-Replay-Regeln ausführen. Typisches Anwendungsszenario: Bei der Entwicklung oder dem Testen eines E-Commerce-Flash-Sale-Events, da das Zeitfenster für den Flash-Sale extrem kurz ist, verpasst manuelles Klicken oft den genauen Moment. Zu diesem Zeitpunkt können Sie eine geplante Aufgabe so konfigurieren, dass die API die Auftragseinreichung automatisch und mit hoher Häufigkeit anfordert, kurz bevor der Flash-Sale beginnt. Dies hilft Ihnen, die Parallelitätsstabilität und die Geschäftslogik der Flash-Sale-Verbindung vollständig zu überprüfen.

6.1 Zeitplankonfiguration (Schedule Type)

Cron-Ausdruck: Verwendet die Standard-Cron-Syntax mit 5 Feldern (z. B. bedeutet */5 * * * * eine Ausführung alle 5 Minuten). Sie können die integrierte KI-Unterstützung verwenden, um sie zu generieren.
Benutzerdefinierte Konfiguration: Unterstützt die fein abgestimmte Einstellung von Startzeit, Intervall und maximaler Anzahl von Ausführungen.

6.2 Automatische Beendigungsbedingungen (Auto Terminate)

Legen Sie Beendigungsbedingungen fest, um sinnlose Wiederholungsversuche in abnormalen Situationen zu vermeiden oder nach Erreichen des Ziels automatisch zu beenden:

JSON-Felder abgleichen: Beispielsweise überwachen Sie im Szenario "Flash-Sale-Test" das Feld code des zurückgegebenen Ergebnisses. Sobald der code gleich 200 (Kauf erfolgreich gesendet) oder gleich 400 (Inventar leer und Ereignis beendet) ist, wird die Beendigung ausgelöst.
Abgleich regulärer Ausdrücke: Führen Sie einen Volltextabgleich im Antworttext durch. Solange die Zeichensignaturen wie "msg": "Kauf erfolgreich" oder "error": "Das Ereignis ist beendet" übereinstimmen, wird die Aufgabe automatisch vollständig gestoppt.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Die Aufgabe kann nicht ausgeführt werden: Das iOS-System verfügt über strenge Hintergrundkontrollen. Bei knappem Speicherplatz kann der VPN-Prozess vom System zurückgefordert werden, und geplante Aufgaben pausieren zusammen mit ihm.

Keine Verlaufsaufzeichnungen angezeigt: Geplante Aufgaben überwachen Anforderungen, die direkt von der zugrunde liegenden Engine initiiert wurden, und werden nicht im regulären "Verlauf" der Haupt-App aufgezeichnet. Sie müssen Berichte wie die Erfolgsquote und p95 im exklusiven Aufgabenbereich "Ausführungsverlauf" anzeigen.

Regelaktualisierungen werden nicht wirksam: Geplante Aufgaben werden zum Zeitpunkt der Erstellung an einen Snapshot der Regel gebunden. Wenn die ursprüngliche "Combo Replay"-Regel geändert wird, muss die geplante Aufgabe neu erstellt werden.

7. Fehlerbehebung bei Qualität und Leistung: API-Scan (API Scan)

Basierend auf den lokal erfassten Verkehrsdaten bietet es nicht-intrusive Gesundheitschecks zur API-Qualität, Sicherheits-Compliance und Leistung. Alle Analysen werden vollständig innerhalb der lokalen Speicherschleife des Geräts durchgeführt.

7.1 Eingebaute Scan-Engine

Sensible Informationen Selbstprüfung: Unterstützt die Erkennung der Klartextübertragung von Telefonnummern, ID-Karten, E-Mails und Cloud-Service-Anmeldeinformationen (wie AWS Keys, OpenAI API Keys) und hilft Frontend- und API-Designern, Auslassungen bei der Datendesensibilisierung frühzeitig zu erkennen.
Abnormales Stapelleck: Identifiziert unachtsam zurückgegebene Java-, Python- oder SQL-Fehleraufrufstapel in Antworttexten.
Hochfrequenz-Anrufanalyse: Basierend auf festgelegten Schwellenwerten (z. B. ist das durchschnittliche Anforderungsintervall kleiner als eine bestimmte Anzahl von Millisekunden), behebt das Problem, ob redundante API-Aufrufe vorhanden sind, die durch Endlosschleifen oder falsche Logik verursacht wurden.
Zeitraumbewertung: Aggregiert und berechnet p95- und p99-Latenzen für verschiedene APIs und hilft dabei, Backend-Leistungsengpässe zu lokalisieren.

7.2 Benutzerdefinierte Qualitätserkennung (Custom Scan)

Sie können JS-Skripte schreiben, um Compliance-Prüfungen auszuführen, die an Ihr Geschäft angepasst sind.

Rückgabewertkonvention: Wenn die Funktion der Ansicht ist, dass die Anforderung den Erwartungen entspricht, gibt sie null zurück. Wenn eine Nichtübereinstimmung festgestellt wird (z. B. ein zu großer Antworttext, fehlende Sicherheitsheader), geben Sie eine kurze Beschreibung (≤200 Zeichen) zurück, und das System fügt diese automatisch in den Scanbericht ein.

💡 Allgemeine Anleitung zur Fehlerbehebung:

Keine Ergebnisse analysiert: Bestätigen Sie, ob der "Scan-Bereich (Host/Session)" tatsächlich gültige JSON/API-Verkehrsaufzeichnungen enthält und keine reinen statischen Ressourcen. Um eine gute Erfahrung zu gewährleisten, gibt es ein maximales Limit für Aufzeichnungen für einen einzelnen Scan.

8. Dienstprogramme: Verschlüsselung/Entschlüsselung & Desktop-Synchronisierung

8.1 Entwickler-Toolbox (Decrypt/Encrypt)

Um die verschlüsselte Übertragung der Nutzdaten zu bewältigen, sind gängige Codec-Tools integriert:

AES-Entschlüsselung: Unterstützt die Eingabe von benutzerdefinierten Schlüsseln (Key) und Initialisierungsvektoren (IV), um Payloads schnell zu entschlüsseln und zu testen.
Base64 / URL Encode / MD5 / SHA256.
Benutzerdefinierte Verarbeitung: Unterstützt das Schreiben von JS-Snippets, die einmal ausgeführt werden, um eine Datentransformation am ausgewählten Text durchzuführen.

8.2 Echtzeitsynchronisierung auf dem Desktop (Realtime Sync)

Verwendung: Wenn Sie Daten mit einer breiteren Ansicht auf einem PC debuggen müssen, können Sie vom Gerät erfasste Datenpakete nahtlos über das WebSocket-Protokoll in die Desktopanwendung ApiCatcher Desktop übertragen. Konfiguration:

Geben Sie die im lokalen Netzwerk zugewiesene WebSocket-Adresse ein.
Stellen Sie sicher, dass Sie den "Verbindungstest" bestehen, um den Erfolg des Handshakes zu überprüfen.
Fehlerbehebung: Stellen Sie sicher, dass dem mobilen Terminal die Berechtigung "Lokales Netzwerk" erteilt wurde, die PC-Firewall den entsprechenden Port zugelassen hat und stellen Sie sicher, dass sich beide im selben LAN-Subnetz befinden.