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 kroku | Co robisz w UI | Typowe zastosowanie |
|---|---|---|
| Skrypt | Napisz kawałek JavaScript | Zmiana nagłówków/body, podpisywanie, deszyfrowanie, logika warunkowa |
| Skrypt biblioteczny | Odwołaj się do zapisanego współdzielonego skryptu | Ponowne użycie „wstrzykiwania tokenu”, „zunifikowanego logowania” w wielu miejscach |
| Ekstrakcja | Pobierz wartość z odpowiedzi i zapisz ją jako zmienną | Przekaż token logowania do następnego żądania |
| Asercja | Dodaj jedną walidację odpowiedzi | Kod statusu = 200, istnienie pola |
| Czekaj | Wstrzymaj na zadaną liczbę milisekund | Limitowanie 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;
}
onRequestpisz 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.
awaitjest obsługiwane.
Co skrypty mogą zmieniać
Zmiana żądania (obiekt request w onRequest)
| Chcesz | Jak |
|---|---|
| Ustawić / nadpisać nagłówek | request.headers.set('Authorization', 'Bearer ' + tok) |
| Dodać / zmienić parametr zapytania | request.queries.set('ts', String(Date.now())) |
| Odczytać surowe body | var text = request.body.parseText() albo request.body.parseJSON() |
| Przepisać całe body | request.body = the new string (zwykłe przypisanie) |
Odczyt / zmiana odpowiedzi (obiekt response w onResponse)
| Chcesz | Jak |
|---|---|
| Odczytać kod statusu | response.statusCode |
| Odczytać nagłówek odpowiedzi | response.headers.get('Set-Cookie') |
| Odczytać body | response.body.parseJSON() / .parseText() |
| Przepisać całe body odpowiedzi | response.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 testy | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Zapytania JSONPath | sdk.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ów | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Silnikiem jest QuickJS: nie ma przeglądarkowego
crypto.subtle, acrypto.getRandomValuesnie działa w tym silniku (nie wypełnia przekazanej tablicy) — do AES użyj$crypto, a do losowościcrypto.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:
- Identyfikator biblioteki skryptów — dokładne dopasowanie, stabilny mimo zmian nazwy (zalecane)
- Nazwa biblioteki skryptów — czytelna, ale zmiana nazwy biblioteki psuje odwołanie (niejednoznaczne duplikaty są pomijane)
- Wbudowane biblioteki — dołączone do aplikacji
Wbudowane biblioteki
| Klucz | Eksporty | Uwagi |
|---|---|---|
@libs/base64 | encode(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/hex | encode(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=iifealbo Browserify/Webpack), zaimportuj ten plik jako bibliotekę skryptów, a potemrequire('@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łaniarequirew 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.