Passa al contenuto principale

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 stepCosa fai nella UIUso tipico
ScriptScrivi un pezzo di JavaScriptCambiare header/corpo, firma, decifratura, logica condizionale
Library scriptReferenzia uno script condiviso salvatoRiutilizzare «allega token», «logging unificato» in molti punti
ExtractPrendi un valore dalla risposta e salvalo come variabilePassare il token di login alla richiesta successiva
AssertAggiungi una validazione sulla rispostaCodice di stato = 200, un campo esiste
WaitPausa di alcuni millisecondiRate 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 onRequest nella catena di pre-invio, onResponse nella 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)​

VuoiCome
Impostare / sovrascrivere un headerrequest.headers.set('Authorization', 'Bearer ' + tok)
Aggiungere / cambiare un parametro di queryrequest.queries.set('ts', String(Date.now()))
Leggere il corpo grezzovar text = request.body.parseText() oppure request.body.parseJSON()
Riscrivere l'intero corporequest.body = the new string (assegnazione semplice)

Leggere / modificare la risposta (l'oggetto response in onResponse)​

VuoiCome
Leggere il codice di statoresponse.statusCode
Leggere un header di rispostaresponse.headers.get('Set-Cookie')
Leggere il corporesponse.body.parseJSON() / .parseText()
Riscrivere l'intero corpo della rispostaresponse.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 dichiarativisdk.test('lo stato dovrebbe essere 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Query JSONPathsdk.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 stringhesdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Il motore è QuickJS: non esiste il crypto.subtle dei browser, e crypto.getRandomValues non funziona in questo motore (non riempie l'array passato) — usa $crypto per AES, e crypto.randomUUID / $uuid per 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:

  1. Identificatore della libreria di script — corrispondenza esatta, stabile attraverso i rinomini (consigliato)
  2. Nome della libreria di script — leggibile, ma rinominare la libreria rompe il riferimento (i nomi duplicati ambigui vengono ignorati)
  3. Librerie integrate — incluse nell'app

Librerie integrate​

ChiaveEsportazioniNote
@libs/base64encode(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/hexencode(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 require di 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 fai require('@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 chiamate require dentro 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.