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:
| Staptype | Wat je in de UI doet | Typisch gebruik |
|---|---|---|
| Script | Schrijf een stuk JavaScript | Headers/body wijzigen, ondertekening, ontsleuteling, voorwaardelijke logica |
| Bibliotheekscript | Verwijs naar een opgeslagen gedeeld script | 'Token injecteren', 'uniforme logging' op veel plaatsen hergebruiken |
| Extractie | Neem een waarde uit het antwoord en sla die op als variabele | De logintoken doorgeven aan het volgende verzoek |
| Assertie | Voeg één validatie op het antwoord toe | Statuscode = 200, een veld bestaat |
| Wacht | Pauzeer enkele milliseconden | Rate 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
onRequestin de keten vóór verzending,onResponsein de keten na het antwoord. - De functienamen moeten exact deze zijn, anders wordt het script behandeld als 'geen entrypunt' en overgeslagen.
awaitwordt ondersteund.
Wat scripts kunnen wijzigen
Het verzoek wijzigen (het request-object in onRequest)
| Je wilt | Zo |
|---|---|
| Een header instellen / overschrijven | request.headers.set('Authorization', 'Bearer ' + tok) |
| Een queryparameter toevoegen / wijzigen | request.queries.set('ts', String(Date.now())) |
| De raw body lezen | var text = request.body.parseText() of request.body.parseJSON() |
| De hele body herschrijven | request.body = the new string (gewone toewijzing) |
Het antwoord lezen / wijzigen (het response-object in onResponse)
| Je wilt | Zo |
|---|---|
| De statuscode lezen | response.statusCode |
| Een antwoordheader lezen | response.headers.get('Set-Cookie') |
| De body lezen | response.body.parseJSON() / .parseText() |
| De hele antwoord-body herschrijven | response.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:
| Mogelijkheid | Wat te gebruiken |
|---|---|
| Variabelen lezen / schrijven (doorgeven tussen verzoeken) | sdk.env.get(name) / sdk.env.set(name, value) |
| Declaratieve tests | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| JSONPath-query's | sdk.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 base64 | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ De engine is QuickJS: er is geen browser-
crypto.subtle, encrypto.getRandomValueswerkt niet in deze engine (het vult de meegegeven array niet) — gebruik$cryptovoor AES, encrypto.randomUUID/$uuidvoor 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:
- Identificator van de scriptbibliotheek — exacte match, stabiel bij hernoemen (aanbevolen)
- Naam van de scriptbibliotheek — leesbaar, maar het hernoemen van de bibliotheek breekt de verwijzing (dubbelzinnige duplicaten worden overgeslagen)
- Ingebouwde bibliotheken — meegeleverd met de app
Ingebouwde bibliotheken
| Key | Exports | Opmerkingen |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | UTF-8-veilige Base64 (Chinees & emoji-veilig); decode negeert witruimte, ongeldige sequenties blijven als Latin-1 |
@libs/hex | encode(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 danrequire('@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.