Przejdź do głównej zawartości

Skrypty (widok dewelopera)

Skrypty przed wysłaniem / po odpowiedzi to scyzoryk szwajcarski Quick Request: dynamiczne podpisywanie, szyfrowanie i deszyfrowanie, warunkowe asercje i przekazywanie wartości między żądaniami — wszystko to dzieje się tutaj. Skrypty pisze się w JavaScript i uruchamia we wbudowanym silniku QuickJS.

Ta strona opisuje wyłącznie co można dodać w UI i co potrafią skrypty; pełne sygnatury JavaScript API znajdziesz w Dokumentacji API skryptów.


Jedno żądanie ma dwa „łańcuchy akcji”​

Na stronie edytora żądania możesz dodać kilka kroków do łańcuchów przed wysłaniem i po odpowiedzi; wykonują się po kolei. Każdy krok to jeden z typów:

Typ krokuCo robisz w UITypowe zastosowanie
SkryptNapisz kawałek JavaScriptZmiana nagłówków/body, podpisywanie, deszyfrowanie, logika warunkowa
Skrypt bibliotecznyOdwołaj się do zapisanego współdzielonego skryptuPonowne użycie „wstrzykiwania tokenu”, „zunifikowanego logowania” w wielu miejscach
EkstrakcjaPobierz wartość z odpowiedzi i zapisz ją jako zmiennąPrzekaż token logowania do następnego żądania
AsercjaDodaj jedną walidację odpowiedziKod statusu = 200, istnienie pola
CzekajWstrzymaj na zadaną liczbę milisekundLimitowanie częstotliwości, interwały odpytywania

Jak pisać skrypty: dwa punkty wejścia​

Silnik skryptów szuka w Twoim skrypcie znanych funkcji wejściowych:

// 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;
}
  • onRequest pisz w łańcuchu przed wysłaniem, onResponse — w łańcuchu po odpowiedzi.
  • Nazwy funkcji muszą być dokładnie takie, inaczej skrypt zostanie uznany za „bez punktu wejścia” i pominięty.
  • await jest obsługiwane.

Co skrypty mogą zmieniać​

Zmiana żądania (obiekt request w onRequest)​

ChceszJak
Ustawić / nadpisać nagłówekrequest.headers.set('Authorization', 'Bearer ' + tok)
Dodać / zmienić parametr zapytaniarequest.queries.set('ts', String(Date.now()))
Odczytać surowe bodyvar text = request.body.parseText() albo request.body.parseJSON()
Przepisać całe bodyrequest.body = the new string (zwykłe przypisanie)

Odczyt / zmiana odpowiedzi (obiekt response w onResponse)​

ChceszJak
Odczytać kod statusuresponse.statusCode
Odczytać nagłówek odpowiedziresponse.headers.get('Set-Cookie')
Odczytać bodyresponse.body.parseJSON() / .parseText()
Przepisać całe body odpowiedziresponse.body = the new string — widok UI/wyniku pokazuje przepisaną treść (zweryfikowano)

Wbudowane możliwości — nie wynajduj koła na nowo​

Skrypty dostają zestaw wbudowanych narzędzi (sdk.*) i natywnych możliwości z prefiksem $: szyfrowanie, funkcje skrótu, kodowanie, losowość i JSONPath — wszystko pokryte:

MożliwośćCzego użyć
Odczyt / zapis zmiennych (przekazywanie między żądaniami)sdk.env.get(name) / sdk.env.set(name, value)
Deklaratywne testysdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Zapytania JSONPathsdk.jsonPath('$.data.id')
Szyfrowanie / deszyfrowanie AES$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
Skróty MD5 / SHA (podpisywanie)$hash.md5(...) / $hash.sha256(...) (zwraca hex, standardowe i interoperacyjne)
UUID$uuid.v4()
Base64 na ciągach znakówsdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Silnikiem jest QuickJS: nie ma przeglądarkowego crypto.subtle, a crypto.getRandomValues nie działa w tym silniku (nie wypełnia przekazanej tablicy) — do AES użyj $crypto, a do losowości crypto.randomUUID / $uuid. Nie sięgaj po WebCrypto. Pełne sygnatury i zastrzeżenia: Dokumentacja API skryptów.


Ładowanie bibliotek skryptów przez require()​

Wspólną logikę można też ładować przez require() w stylu CommonJS, zamiast dodawać ją jako krok. Klucz to zawsze @libs/<key>, rozwiązywany w tej kolejności:

  1. Identyfikator biblioteki skryptów — dokładne dopasowanie, stabilny mimo zmian nazwy (zalecane)
  2. Nazwa biblioteki skryptów — czytelna, ale zmiana nazwy biblioteki psuje odwołanie (niejednoznaczne duplikaty są pomijane)
  3. Wbudowane biblioteki — dołączone do aplikacji

Wbudowane biblioteki​

KluczEksportyUwagi
@libs/base64encode(str) / decode(text)Base64 bezpieczne dla UTF-8 (znaki chińskie i emoji bezpieczne); decode ignoruje białe znaki, niepoprawne sekwencje traktuje jak Latin-1
@libs/hexencode(str) / decode(text)Małe litery hex, bezpieczne dla UTF-8; decode ignoruje znaki spoza hex, nieparzysta długość rzuca wyjątek

Oba są też wystawione jako globalne aliasy (base64.encode(...) / hex.encode(...)) — require daje po prostu jawny styl importu.

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

Własne biblioteki skryptów​

Zapisz funkcje wielokrotnego użytku jako bibliotekę skryptów (eksport przez module.exports, funkcja wejściowa niewymagana) i ładuj ją z dowolnego skryptu przed/po:

// 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;
}
  • Użyj Copy require statement w menedżerze bibliotek, aby uzyskać stabilną formę identyfikatora.
  • Biblioteki mogą require-ować inne biblioteki — cała domknięta zależność jest pakowana automatycznie (cykle rozwiązywane po Node-owsku, bez nieskończonej pętli).
  • Cache modułów jest odbudowywany przy każdym wykonaniu: biblioteki nigdy nie przenoszą stanu między żądaniami.
  • Aby użyć pakietu npm, najpierw spakuj go do jednego pliku (np. esbuild --format=iife albo Browserify/Webpack), zaimportuj ten plik jako bibliotekę skryptów, a potem require('@libs/<name>'). Wybieraj czyste buildy JS bez zależności od Node (Buffer/fs/crypto/process) ani DOM.
  • Brakujący klucz rzuca Error: require: 未找到库 [...] — niepowodzenie przed wysłaniem przerywa żądanie, niepowodzenie po odpowiedzi zachowuje oryginalną odpowiedź. Wywołania require w komentarzach są ignorowane.

Pełna semantyka require: Dokumentacja API skryptów.


Jak współpracuje wiele skryptów​

Gdy żądanie ma kilka skryptów, współdzielą one ten sam globalThis (zweryfikowano). Dzięki temu możesz:

Zalety: każdy skrypt ma jedną odpowiedzialność i można go niezależnie włączać i wyłączać. „Skrypt biblioteczny” to też pełny skrypt (z własnym onRequest/onResponse) — dodaj go jako krok, aby wykonać cały łańcuch, albo trzymaj w nim czyste funkcje przez module.exports i ładuj je przez require('@libs/<key>') (zobacz Ładowanie bibliotek skryptów przez require()).

Konkretne przykłady łańcuchów (logowanie po token, pełny obieg AES) znajdziesz w recipes.