Scripting (vista sviluppatore)
Gli script di pre-invio / post-risposta sono il coltellino svizzero di Quick Request: firma dinamica, cifratura e decifratura, asserzioni condizionali e passaggio di valori tra richieste vivono qui. Gli script si scrivono in JavaScript e girano nel motore QuickJS integrato.
Questa pagina copre solo cosa puoi aggiungere nella UI e cosa possono fare gli script; per le firme complete delle API JavaScript vedi il Riferimento API degli script.
Una richiesta ha due «catene di azioni»
Nella pagina di modifica della richiesta puoi aggiungere più step alle catene di pre-invio e post-risposta; vengono eseguiti in ordine. Ogni step è uno dei seguenti:
| Tipo di step | Cosa fai nella UI | Uso tipico |
|---|---|---|
| Script | Scrivi un pezzo di JavaScript | Cambiare header/corpo, firma, decifratura, logica condizionale |
| Library script | Referenzia uno script condiviso salvato | Riutilizzare «allega token», «logging unificato» in molti punti |
| Extract | Prendi un valore dalla risposta e salvalo come variabile | Passare il token di login alla richiesta successiva |
| Assert | Aggiungi una validazione sulla risposta | Codice di stato = 200, un campo esiste |
| Wait | Pausa di alcuni millisecondi | Rate limiting, intervalli di polling |
Come scrivere gli script: due punti di ingresso
Il motore degli script cerca le funzioni di ingresso note nel tuo 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;
}
- Scrivi
onRequestnella catena di pre-invio,onResponsenella catena post-risposta. - I nomi delle funzioni devono essere esattamente questi, altrimenti lo script viene considerato «senza punto di ingresso» e ignorato.
awaitè supportato.
Cosa possono cambiare gli script
Modificare la richiesta (l'oggetto request in onRequest)
| Vuoi | Come |
|---|---|
| Impostare / sovrascrivere un header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Aggiungere / cambiare un parametro di query | request.queries.set('ts', String(Date.now())) |
| Leggere il corpo grezzo | var text = request.body.parseText() oppure request.body.parseJSON() |
| Riscrivere l'intero corpo | request.body = the new string (assegnazione semplice) |
Leggere / modificare la risposta (l'oggetto response in onResponse)
| Vuoi | Come |
|---|---|
| Leggere il codice di stato | response.statusCode |
| Leggere un header di risposta | response.headers.get('Set-Cookie') |
| Leggere il corpo | response.body.parseJSON() / .parseText() |
| Riscrivere l'intero corpo della risposta | response.body = the new string — la vista UI/risultato mostra il contenuto riscritto (verificato) |
Capacità integrate — niente da reinventare
Gli script includono una serie di strumenti integrati (sdk.*) e capacità native con prefisso $: cifratura, digest, codifica, casualità e JSONPath sono tutti coperti:
| Capacità | Cosa usare |
|---|---|
| Leggere / scrivere variabili (passaggio tra richieste) | sdk.env.get(name) / sdk.env.set(name, value) |
| Test dichiarativi | sdk.test('lo stato dovrebbe essere 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Query JSONPath | sdk.jsonPath('$.data.id') |
| Cifratura / decifratura AES | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| Digest MD5 / SHA (firma) | $hash.md5(...) / $hash.sha256(...) (restituisce hex, standard e interoperabile) |
| UUID | $uuid.v4() |
| Base64 di stringhe | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Il motore è QuickJS: non esiste il
crypto.subtledei browser, ecrypto.getRandomValuesnon funziona in questo motore (non riempie l'array passato) — usa$cryptoper AES, ecrypto.randomUUID/$uuidper la casualità. Non puntare a WebCrypto. Firme complete e avvertenze: Riferimento API degli script.
Importare librerie di script
Anche la logica condivisa può essere caricata con require() in stile CommonJS invece di essere aggiunta come step. La chiave è sempre @libs/<key>, risolta in questo ordine:
- Identificatore della libreria di script — corrispondenza esatta, stabile attraverso i rinomini (consigliato)
- Nome della libreria di script — leggibile, ma rinominare la libreria rompe il riferimento (i nomi duplicati ambigui vengono ignorati)
- Librerie integrate — incluse nell'app
Librerie integrate
| Chiave | Esportazioni | Note |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | Base64 sicuro UTF-8 (sicuro per cinese ed emoji); decode ignora gli spazi bianchi, le sequenze non valide restano Latin-1 |
@libs/hex | encode(str) / decode(text) | Hex minuscolo sicuro UTF-8; decode ignora i caratteri non hex, la lunghezza dispari lancia un errore |
Entrambe sono esposte anche come alias globali (base64.encode(...) / hex.encode(...)) — require ti offre solo lo stile di importazione esplicito.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Le tue librerie di script
Salva le funzioni riutilizzabili come libreria di script (esportazione via module.exports, nessuna funzione di ingresso richiesta) e richiamala con require da qualunque script pre/post:
// 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;
}
- Usa Copia istruzione require nel gestore delle librerie per ottenere la forma a identificatore stabile.
- Le librerie possono fare
requiredi altre librerie — l'intera chiusura delle dipendenze viene inclusa automaticamente (i cicli si risolvono in stile Node, nessun loop infinito). - La cache dei moduli viene ricostruita a ogni esecuzione: le librerie non portano stato tra le richieste.
- Per riutilizzare un pacchetto npm, prima aggregalo in un singolo file (es.
esbuild --format=iife, oppure Browserify/Webpack), importa il file come libreria di script, poi fairequire('@libs/<name>'). Scegli build JS pure senza dipendenze Node (Buffer/fs/crypto/process) né DOM. - Una chiave mancante lancia
Error: require: 未找到库 [...]— un fallimento in pre-invio abortisce la richiesta, in post-risposta la risposta originale viene conservata. Le chiamaterequiredentro i commenti vengono ignorate.
Semantica completa di require: Riferimento API degli script.
Come cooperano più script
Quando una richiesta ha più script, essi condividono lo stesso globalThis (verificato). Quindi puoi:
Vantaggi: ogni script ha una singola responsabilità e può essere attivato/disattivato indipendentemente. Anche uno «script di libreria» è uno script completo (con i propri onRequest/onResponse) — aggiungilo come step per eseguire l'intera catena, oppure custodisci al suo interno funzioni pure con module.exports e caricale con require('@libs/<key>') (vedi Importare librerie di script).
Per esempi concatenati concreti (login per il token, round-trip AES) vedi recipes.