Ga naar hoofdinhoud

Scripting (ontwikkelaarsweergave)

Scripts vóór verzending / na het antwoord zijn het Zwitserse zakmes van Quick Request: dynamische ondertekening, versleuteling & ontsleuteling, voorwaardelijke asserties en het doorgeven van waarden tussen verzoeken komen hier allemaal samen. Scripts worden geschreven in JavaScript en draaien in de ingebouwde QuickJS-engine.

Deze pagina behandelt alleen wat je in de UI kunt toevoegen en wat scripts kunnen; voor de volledige JavaScript-API-handtekeningen zie de Script-API-referentie.


Eén verzoek heeft twee 'actieketens'​

Op de pagina van de verzoekeditor kun je meerdere stappen toevoegen aan de keten vóór verzending en aan de keten na het antwoord; ze draaien in volgorde. Elke stap is één van:

StaptypeWat je in de UI doetTypisch gebruik
ScriptSchrijf een stuk JavaScriptHeaders/body wijzigen, ondertekening, ontsleuteling, voorwaardelijke logica
BibliotheekscriptVerwijs naar een opgeslagen gedeeld script'Token injecteren', 'uniforme logging' op veel plaatsen hergebruiken
ExtractieNeem een waarde uit het antwoord en sla die op als variabeleDe logintoken doorgeven aan het volgende verzoek
AssertieVoeg één validatie op het antwoord toeStatuscode = 200, een veld bestaat
WachtPauzeer enkele millisecondenRate limiting, polling-intervallen

Hoe schrijf je scripts: twee toegangspunten​

De scriptengine zoekt naar bekende entryfuncties in je script:

// 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;
}
  • Schrijf onRequest in de keten vóór verzending, onResponse in de keten na het antwoord.
  • De functienamen moeten exact deze zijn, anders wordt het script behandeld als 'geen entrypunt' en overgeslagen.
  • await wordt ondersteund.

Wat scripts kunnen wijzigen​

Het verzoek wijzigen (het request-object in onRequest)​

Je wiltZo
Een header instellen / overschrijvenrequest.headers.set('Authorization', 'Bearer ' + tok)
Een queryparameter toevoegen / wijzigenrequest.queries.set('ts', String(Date.now()))
De raw body lezenvar text = request.body.parseText() of request.body.parseJSON()
De hele body herschrijvenrequest.body = the new string (gewone toewijzing)

Het antwoord lezen / wijzigen (het response-object in onResponse)​

Je wiltZo
De statuscode lezenresponse.statusCode
Een antwoordheader lezenresponse.headers.get('Set-Cookie')
De body lezenresponse.body.parseJSON() / .parseText()
De hele antwoord-body herschrijvenresponse.body = the new string — de UI/resultaatweergave toont de herschreven inhoud (geverifieerd)

Ingebouwde mogelijkheden — niets opnieuw uitvinden​

Scripts worden geleverd met een reeks ingebouwde hulpmiddelen (sdk.*) en native mogelijkheden met $-voorvoegsel: versleuteling, digests, encoding, willekeur en JSONPath zijn allemaal gedekt:

MogelijkheidWat te gebruiken
Variabelen lezen / schrijven (doorgeven tussen verzoeken)sdk.env.get(name) / sdk.env.set(name, value)
Declaratieve testssdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
JSONPath-query'ssdk.jsonPath('$.data.id')
AES-versleuteling / -ontsleuteling$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
MD5 / SHA-digests (ondertekening)$hash.md5(...) / $hash.sha256(...) (geeft hex terug, standaard & interoperabel)
UUID$uuid.v4()
String base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ De engine is QuickJS: er is geen browser-crypto.subtle, en crypto.getRandomValues werkt niet in deze engine (het vult de meegegeven array niet) — gebruik $crypto voor AES, en crypto.randomUUID / $uuid voor willekeur. Grijp niet naar WebCrypto. Volledige handtekeningen en kanttekeningen: Script-API-referentie.


Scriptbibliotheken laden met require()​

Gedeelde logica kan ook worden geladen met require() in CommonJS-stijl in plaats van als stap te worden toegevoegd. De key is altijd @libs/<key>, opgelost in deze volgorde:

  1. Identificator van de scriptbibliotheek — exacte match, stabiel bij hernoemen (aanbevolen)
  2. Naam van de scriptbibliotheek — leesbaar, maar het hernoemen van de bibliotheek breekt de verwijzing (dubbelzinnige duplicaten worden overgeslagen)
  3. Ingebouwde bibliotheken — meegeleverd met de app

Ingebouwde bibliotheken​

KeyExportsOpmerkingen
@libs/base64encode(str) / decode(text)UTF-8-veilige Base64 (Chinees & emoji-veilig); decode negeert witruimte, ongeldige sequenties blijven als Latin-1
@libs/hexencode(str) / decode(text)UTF-8-veilige hex in kleine letters; decode negeert niet-hex-tekens, oneven lengte gooit een fout

Beide zijn ook beschikbaar als globale aliassen (base64.encode(...) / hex.encode(...)) — require geeft je alleen de expliciete importstijl.

const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'

Je eigen scriptbibliotheken​

Bewaar herbruikbare functies als een scriptbibliotheek (export via module.exports, geen entryfunctie nodig) en laad ze vanuit elk pre/post-script:

// 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;
}
  • Gebruik Require-instructie kopiëren in de bibliotheekbeheerder om de vorm met de stabiele identificator te krijgen.
  • Bibliotheken mogen andere bibliotheken laden met require — de volledige afhankelijkheidsketen wordt automatisch meegebundeld (cycli worden op Node-stijl opgelost, geen oneindige lus).
  • De modulecache wordt bij elke uitvoering opnieuw opgebouwd: bibliotheken nemen nooit toestand mee tussen verzoeken.
  • Om een npm-pakket te hergebruiken: bundel het eerst tot één bestand (bijv. met esbuild --format=iife, of Browserify/Webpack), importeer dat bestand als scriptbibliotheek en gebruik dan require('@libs/<name>'). Kies pure JS-builds zonder Node-afhankelijkheden (Buffer/fs/crypto/process) en zonder DOM-afhankelijkheden.
  • Een ontbrekende key gooit Error: require: 未找到库 [...] — fouten vóór verzending breken het verzoek af, fouten na het antwoord behouden het oorspronkelijke antwoord. require-aanroepen binnen commentaar worden genegeerd.

Volledige require-semantiek: Script-API-referentie.


Hoe meerdere scripts samenwerken​

Als een verzoek meerdere scripts heeft, delen ze dezelfde globalThis (geverifieerd). Je kunt dus:

Voordelen: elk script heeft één duidelijke verantwoordelijkheid en kan onafhankelijk worden in- of uitgeschakeld. Een 'bibliotheekscript' is ook een compleet script (met zijn eigen onRequest/onResponse) — voeg het als stap toe om de hele keten te draaien, of bewaar pure functies erin met module.exports en laad ze met require('@libs/<key>') (zie Scriptbibliotheken laden met require()).

Voor concrete ketenvoorbeelden (inloggen voor de token, AES heen en weer) zie recipes.