Skripte (Entwicklersicht)
Pre-Send-/Post-Response-Skripte sind das Schweizer Taschenmesser von Quick Request: dynamische Signatur, Ver- und Entschlüsselung, bedingte Assertions und requestübergreifende Wertweitergabe leben hier. Skripte werden in JavaScript geschrieben und laufen in der eingebauten QuickJS-Engine.
Diese Seite behandelt nur, was sich in der UI ergänzen lässt und was Skripte können; die vollständigen JavaScript-API-Signaturen finden Sie in der Script-API-Referenz.
Ein Request hat zwei „Aktionsketten“
Auf der Request-Editor-Seite lassen sich der Pre-Send- und der Post-Response-Kette mehrere Schritte hinzufügen; sie laufen der Reihe nach. Jeder Schritt ist einer der folgenden:
| Schritttyp | Was Sie in der UI tun | Typischer Einsatz |
|---|---|---|
| Skript | Ein Stück JavaScript schreiben | Headers/Body ändern, Signatur, Entschlüsselung, bedingte Logik |
| Bibliotheksskript | Ein gespeichertes gemeinsames Skript referenzieren | „Token injizieren“, „vereinheitlichtes Logging“ an vielen Stellen wiederverwenden |
| Extraktion | Einen Wert aus der Antwort nehmen und als Variable speichern | Den Login-Token an den nächsten Request weiterreichen |
| Assertion | Eine Prüfung gegen die Antwort ergänzen | Statuscode = 200, ein Feld existiert |
| Warte | Für einige Millisekunden pausieren | Rate-Limiting, Polling-Intervalle |
Wie man Skripte schreibt: zwei Einstiegspunkte
Die Skript-Engine sucht in Ihrem Skript nach bekannten Einstiegsfunktionen:
// Pre-send: can change "the request that is about to go out"
async function onRequest(context, url, request) {
// e.g. inject a header
request.headers.set('X-Trace-Id', $uuid.v4());
return request; // you must return the request
}
// Post-response: can read and change "the response you received"
async function onResponse(context, url, response) {
// e.g. rewrite an encrypted response back to plaintext for humans
return response;
}
onRequestin der Pre-Send-Kette schreiben,onResponsein der Post-Response-Kette.- Die Funktionsnamen müssen exakt so lauten, sonst gilt das Skript als „ohne Einstiegspunkt“ und wird übersprungen.
awaitwird unterstützt.
Was Skripte verändern können
Die Anfrage ändern (das request-Objekt in onRequest)
| Ziel | Wie |
|---|---|
| Header setzen / überschreiben | request.headers.set('Authorization', 'Bearer ' + tok) |
| Query-Parameter ergänzen / ändern | request.queries.set('ts', String(Date.now())) |
| Raw-Body lesen | var text = request.body.parseText() oder request.body.parseJSON() |
| Den ganzen Body umschreiben | request.body = the new string (einfache Zuweisung) |
Die Antwort lesen / ändern (das response-Objekt in onResponse)
| Ziel | Wie |
|---|---|
| Statuscode lesen | response.statusCode |
| Response-Header lesen | response.headers.get('Set-Cookie') |
| Body lesen | response.body.parseJSON() / .parseText() |
| Den ganzen Response-Body umschreiben | response.body = the new string — die UI-/Ergebnisansicht zeigt den umgeschriebenen Inhalt (verifiziert) |
Eingebaute Fähigkeiten — nicht neu erfinden
Skripte bringen eine Reihe eingebauter Werkzeuge mit (sdk.*) sowie $-präfixierte native Fähigkeiten: Verschlüsselung, Digests, Kodierung, Zufall und JSONPath sind alle abgedeckt:
| Fähigkeit | Womit |
|---|---|
| Variablen lesen / schreiben (requestübergreifend) | sdk.env.get(name) / sdk.env.set(name, value) |
| Deklarative Tests | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| JSONPath-Abfragen | sdk.jsonPath('$.data.id') |
| AES-Ver-/Entschlüsselung | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| MD5-/SHA-Digests (Signatur) | $hash.md5(...) / $hash.sha256(...) (liefert Hex, standardkonform & interoperabel) |
| UUID | $uuid.v4() |
| String-Base64 | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Die Engine ist QuickJS: es gibt kein Browser-
crypto.subtle, undcrypto.getRandomValuesfunktioniert in dieser Engine nicht (sie füllt das übergebene Array nicht) — für AES$cryptoverwenden, für Zufallcrypto.randomUUID/$uuid. Greifen Sie nicht zu WebCrypto. Vollständige Signaturen und Hinweise: Script-API-Referenz.
Require-Script-Libraries
Gemeinsame Logik lässt sich auch per require() im CommonJS-Stil laden, statt als Schritt angehängt zu werden. Der Schlüssel ist immer @libs/<key> und wird in dieser Reihenfolge aufgelöst:
- Skriptbibliotheks-Identifier — exakte Übereinstimmung, stabil über Umbenennungen (empfohlen)
- Skriptbibliotheks-Name — lesbar, aber eine Umbenennung bricht die Referenz (mehrdeutige Duplikate werden übersprungen)
- Eingebaute Bibliotheken — mit der App gebündelt
Eingebaute Bibliotheken
| Schlüssel | Exporte | Hinweise |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | UTF-8-sicheres Base64 (Chinesisch & Emoji sicher); decode ignoriert Whitespace, ungültige Sequenzen bleiben Latin-1 |
@libs/hex | encode(str) / decode(text) | UTF-8-sicheres Kleinbuchstaben-Hex; decode ignoriert Nicht-Hex-Zeichen, ungerade Länge wirft |
Beide sind zusätzlich als globale Aliase verfügbar (base64.encode(...) / hex.encode(...)) — require liefert nur den expliziten Import-Stil.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Eigene Skriptbibliotheken
Wiederverwendbare Funktionen als Skriptbibliothek speichern (Export über module.exports, keine Einstiegsfunktion nötig) und aus jedem Vor-/Nachlauf-Skript laden:
// script library "sign-lib"
function sign(method, path, body, secret) {
return $hmac.sha256(method + path + body, secret);
}
module.exports = { sign };
// any request script
async function onRequest(context, url, request) {
const { sign } = require('@libs/sign-lib');
request.headers.set('X-Sign', sign('POST', request.path, request.body.parseText(), sdk.env.get('secret')));
return request;
}
- Im Bibliotheksmanager Copy require statement verwenden, um die stabile Identifier-Form zu bekommen.
- Bibliotheken dürfen andere Bibliotheken
requiren — der gesamte Abhängigkeitsabschluss wird automatisch gebündelt (Zyklen lösen sich im Node-Stil auf, keine Endlosschleife). - Der Modul-Cache wird bei jeder Ausführung neu aufgebaut: Bibliotheken tragen nie Zustand über Requests hinweg.
- Um ein npm-Paket zu nutzen, es zuerst in eine Datei bündeln (z. B.
esbuild --format=iife, oder Browserify/Webpack), die Datei als Skriptbibliothek importieren, dannrequire('@libs/<name>'). Reine JS-Builds ohne Node- (Buffer/fs/crypto/process) oder DOM-Abhängigkeiten wählen. - Ein fehlender Schlüssel wirft
Error: require: 未找到库 [...]— Pre-Send-Fehler brechen die Anfrage ab, Post-Response-Fehler behalten die ursprüngliche Antwort.require-Aufrufe in Kommentaren werden ignoriert.
Vollständige require-Semantik: Script-API-Referenz.
Wie mehrere Skripte zusammenwirken
Hat ein Request mehrere Skripte, teilen sie sich dasselbe globalThis (verifiziert). So können Sie:
Vorteile: Jedes Skript hat eine einzige Verantwortung und lässt sich unabhängig ein-/ausschalten. Ein „Bibliotheksskript“ ist ebenfalls ein vollständiges Skript (mit eigenem onRequest/onResponse) — als Schritt anhängen, um die ganze Kette laufen zu lassen, oder reine Funktionen per module.exports darin ablegen und mit require('@libs/<key>') laden (siehe Require-Script-Libraries).
Konkrete Kettenbeispiele (Login für Token, AES-Roundtrip) finden Sie in den Rezepten.