Zum Hauptinhalt springen

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:

SchritttypWas Sie in der UI tunTypischer Einsatz
SkriptEin Stück JavaScript schreibenHeaders/Body ändern, Signatur, Entschlüsselung, bedingte Logik
BibliotheksskriptEin gespeichertes gemeinsames Skript referenzieren„Token injizieren“, „vereinheitlichtes Logging“ an vielen Stellen wiederverwenden
ExtraktionEinen Wert aus der Antwort nehmen und als Variable speichernDen Login-Token an den nächsten Request weiterreichen
AssertionEine Prüfung gegen die Antwort ergänzenStatuscode = 200, ein Feld existiert
WarteFür einige Millisekunden pausierenRate-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;
}
  • onRequest in der Pre-Send-Kette schreiben, onResponse in der Post-Response-Kette.
  • Die Funktionsnamen müssen exakt so lauten, sonst gilt das Skript als „ohne Einstiegspunkt“ und wird übersprungen.
  • await wird unterstützt.

Was Skripte verändern können​

Die Anfrage ändern (das request-Objekt in onRequest)​

ZielWie
Header setzen / überschreibenrequest.headers.set('Authorization', 'Bearer ' + tok)
Query-Parameter ergänzen / ändernrequest.queries.set('ts', String(Date.now()))
Raw-Body lesenvar text = request.body.parseText() oder request.body.parseJSON()
Den ganzen Body umschreibenrequest.body = the new string (einfache Zuweisung)

Die Antwort lesen / ändern (das response-Objekt in onResponse)​

ZielWie
Statuscode lesenresponse.statusCode
Response-Header lesenresponse.headers.get('Set-Cookie')
Body lesenresponse.body.parseJSON() / .parseText()
Den ganzen Response-Body umschreibenresponse.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ähigkeitWomit
Variablen lesen / schreiben (requestübergreifend)sdk.env.get(name) / sdk.env.set(name, value)
Deklarative Testssdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
JSONPath-Abfragensdk.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-Base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Die Engine ist QuickJS: es gibt kein Browser-crypto.subtle, und crypto.getRandomValues funktioniert in dieser Engine nicht (sie füllt das übergebene Array nicht) — für AES $crypto verwenden, für Zufall crypto.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:

  1. Skriptbibliotheks-Identifier — exakte Übereinstimmung, stabil über Umbenennungen (empfohlen)
  2. Skriptbibliotheks-Name — lesbar, aber eine Umbenennung bricht die Referenz (mehrdeutige Duplikate werden übersprungen)
  3. Eingebaute Bibliotheken — mit der App gebündelt

Eingebaute Bibliotheken​

SchlüsselExporteHinweise
@libs/base64encode(str) / decode(text)UTF-8-sicheres Base64 (Chinesisch & Emoji sicher); decode ignoriert Whitespace, ungültige Sequenzen bleiben Latin-1
@libs/hexencode(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, dann require('@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.