Scripting (utviklerperspektiv)
Skript før sending / etter svar er Quick Requests sveitsiske lommekniv: dynamisk signering, kryptering og dekryptering, betingede assertion og verdi-overføring på tvers av forespørsler bor alle her. Skript skrives i JavaScript og kjører i den innebygde QuickJS-motoren.
Denne siden dekker bare hva du kan legge til i UI og hva skript kan gjøre; for fullstendige JavaScript API-signaturer se Script API-referansen.
Én forespørsel har to «handlingskjeder»
På forespørselsredigeringssiden kan du legge til flere trinn i kjeden før sending og etter svar; de kjører i rekkefølge. Hvert trinn er ett av:
| Trinntype | Hva du gjør i UI | Typisk bruk |
|---|---|---|
| Skript | Skrive litt JavaScript | Endre headers/body, signering, dekryptering, betinget logikk |
| Skriptbibliotek | Referere et lagret delt skript | Gjenbruke «injiser token», «samlet logging» mange steder |
| Uttrekk | Ta en verdi fra svaret og lagre den som variabel | Overføre innloggingstokenet til neste forespørsel |
| Assertion | Legge til én validering mot svaret | Statuskode = 200, et felt finnes |
| Vent | Pause i noen millisekunder | Hastighetsbegrensning, pollingintervaller |
Slik skriver du skript: to inngangspunkter
Skriptmotoren ser etter velkjente inngangsfunksjoner i skriptet ditt:
// 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;
}
- Skriv
onRequesti kjeden før sending,onResponsei kjeden etter svar. - Funksjonsnavnene må være nøyaktig disse, ellers behandles skriptet som «no entry point» og hoppes over.
awaitstøttes.
Hva skript kan endre
Å endre forespørselen (request-objektet i onRequest)
| Du vil | Hvordan |
|---|---|
| Sette / overstyre en header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Legge til / endre en query-parameter | request.queries.set('ts', String(Date.now())) |
| Lese rå-body | var text = request.body.parseText() eller request.body.parseJSON() |
| Omskrive hele bodyen | request.body = the new string (ren tilordning) |
Å lese / endre svaret (response-objektet i onResponse)
| Du vil | Hvordan |
|---|---|
| Lese statuskoden | response.statusCode |
| Lese en respons-header | response.headers.get('Set-Cookie') |
| Lese bodyen | response.body.parseJSON() / .parseText() |
| Omskrive hele respons-bodyen | response.body = the new string — UI/Resultatvisningen viser det omskrevne innholdet (verifisert) |
Innebygde evner — finn ikke opp hjulet på nytt
Skript følger med en bunke innebygde verktøy (sdk.*) og $-prefiksede native evner: kryptering, digests, koding, tilfeldighet og JSONPath er alle dekket:
| Evne | Hva du bruker |
|---|---|
| Lese / skrive variabler (overføring på tvers av forespørsler) | sdk.env.get(name) / sdk.env.set(name, value) |
| Deklarative tester | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| JSONPath-spørringer | sdk.jsonPath('$.data.id') |
| AES-kryptering / -dekryptering | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| MD5 / SHA-digests (signering) | $hash.md5(...) / $hash.sha256(...) (returnerer hex, standard og interoperabel) |
| UUID | $uuid.v4() |
| String base64 | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Motoren er QuickJS: det finnes ingen browser-
crypto.subtle, ogcrypto.getRandomValuesfungerer ikke i denne motoren (den fyller ikke den gitte matrisen) — bruk$cryptofor AES, ogcrypto.randomUUID/$uuidfor tilfeldighet. Ikke grip etter WebCrypto. Fullstendige signaturer og forbehold: Script API-referansen.
Laste skriptbiblioteker med require()
Delt logikk kan også lastes med CommonJS-stil require() i stedet for å legges til som et trinn. Nøkkelen er alltid @libs/<key>, løst i denne rekkefølgen:
- Skriptbibliotek-identifikator — eksakt samsvar, stabilt på tvers av omdøpinger (anbefales)
- Skriptbibliotek-navn — lesbart, men å omdøpe biblioteket bryter referansen (tvetydige duplikatnavn hoppes over)
- Innebygde biblioteker — følger med appen
Innebygde biblioteker
| Nøkkel | Eksporter | Merknader |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | UTF-8-sikker Base64 (kinesisk og emoji trygt); decode ignorerer mellomrom, ugyldige sekvenser beholdes som Latin-1 |
@libs/hex | encode(str) / decode(text) | UTF-8-sikker lowercase hex; decode ignorerer ikke-hex-tegn, oddelengde kaster feil |
Begge er også eksponert som globale aliaser (base64.encode(...) / hex.encode(...)) — require gir deg bare den eksplisitte importstilen.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Dine egne skriptbiblioteker
Lagre gjenbrukbare funksjoner som et skriptbibliotek (eksport via module.exports, ingen inngangsfunksjon nødvendig) og require det fra hvilket som helst pre/post-skript:
// 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;
}
- Bruk Copy require statement i bibliotekadministratoren for å få den stabile identifikatorformen.
- Biblioteker kan
requireandre biblioteker — hele avhengighetslukningen bundes automatisk (sykluser løses Node-stil, ingen uendelig sløyfe). - Modul-cachen gjenoppbygges ved hver kjøring: biblioteker bærer aldri state på tvers av forespørsler.
- For å gjenbruke en npm-pakke, bundl den først til én fil (f.eks.
esbuild --format=iife, eller Browserify/Webpack), importer filen som et skriptbibliotek, ogrequire('@libs/<name>'). Velg rene JS-bygg uten Node- (Buffer/fs/crypto/process)- eller DOM-avhengigheter. - En manglende nøkkel kaster
Error: require: 未找到库 [...]— feil før sending avbryter forespørselen, feil etter svar beholder originalsvaret.require-kall inne i kommentarer ignoreres.
Full require-semantikk: Script API-referansen.
Slik samarbeider flere skript
Når en forespørsel har flere skript, deler de samme globalThis (verifisert). Så du kan:
Fordeler: hvert skript har ett enkelt ansvar og kan slås av/på uavhengig. Et «skriptbibliotek» er også et fullt skript (med egen onRequest/onResponse) — legg det til som et trinn for å kjøre hele kjeden, eller behold rene funksjoner i det med module.exports og last dem med require('@libs/<key>') (se Skriptbiblioteker med require).
For konkrete kjedeeksempler (innlogging for token, AES-rundtur) se oppskrifter.