Ana içeriğe geç

Script'ler (Geliştirici Görünümü)

Gönderim öncesi / yanıt sonrası script'ler Quick Request'in İsviçre çakısıdır: dinamik imzalama, şifreleme ve çözme, koşullu assertion'lar ve istekler arası değer aktarımı — hepsi burada. Script'ler JavaScript ile yazılır ve yerleşik QuickJS motorunda çalışır.

Bu sayfa yalnızca UI'da ne ekleyebileceğinizi ve script'lerin neler yapabildiğini anlatır; tam JavaScript API imzaları için Script API Referansı'na bakın.


Bir İsteğin İki "Eylem Zinciri" Var​

İstek düzenleyici sayfasında gönderim öncesi ve yanıt sonrası zincirlerine birkaç adım ekleyebilirsiniz; sırayla çalışırlar. Her adım şunlardan biridir:

Adım tipiUI'da ne yaparsınızTipik kullanım
ScriptBir parça JavaScript yazınBaşlık/gövde değiştirme, imzalama, çözme, koşullu mantık
Kütüphane script'iKaydedilmiş paylaşılan bir script'e referans verin"Token enjekte etme", "birleşik logging"i birçok yerde yeniden kullanma
AyıklamaYanıttan bir değer alıp değişken olarak saklayınLogin token'ını sonraki isteğe aktarma
AssertionYanıta bir doğrulama ekleyinDurum kodu = 200, bir alanın varlığı
BeklemeBelirli milisaniye kadar duraklatınHız sınırlama, yoklama aralıkları

Script'ler Nasıl Yazılır: İki Giriş Noktası​

Script motoru, script'inizde bilinen giriş fonksiyonlarını arar:

// 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 gönderim öncesi zincire, onResponse yanıt sonrası zincire yazılır.
  • Fonksiyon adları tam olarak bu olmalıdır, aksi hâlde script "giriş noktası yok" kabul edilip atlanır.
  • await desteklenir.

Script'ler Neyi Değiştirebilir​

İsteği değiştirme (onRequest içindeki request nesnesi)​

İstiyorsunuzNasıl
Başlık ayarla / üzerine yazrequest.headers.set('Authorization', 'Bearer ' + tok)
Sorgu parametresi ekle / değiştirrequest.queries.set('ts', String(Date.now()))
Ham gövdeyi okuvar text = request.body.parseText() ya da request.body.parseJSON()
Tüm gövdeyi yeniden yazrequest.body = the new string (düz atama)

Yanıtı okuma / değiştirme (onResponse içindeki response nesnesi)​

İstiyorsunuzNasıl
Durum kodunu okuresponse.statusCode
Yanıt başlığı okuresponse.headers.get('Set-Cookie')
Gövdeyi okuresponse.body.parseJSON() / .parseText()
Tüm yanıt gövdesini yeniden yazresponse.body = the new string — UI/sonuç görünümü yeniden yazılmış içeriği gösterir (doğrulandı)

Yerleşik Yetenekler — Tekerleği Yeniden İcat Etmeyin​

Script'ler bir dizi yerleşik araçla (sdk.*) ve $ önekli yerel yeteneklerle gelir: şifreleme, özet fonksiyonları, kodlama, rastgelelik ve JSONPath'in hepsi kapsanır:

YetenekNeyi kullanın
Değişken okuma / yazma (istekler arası aktarım)sdk.env.get(name) / sdk.env.set(name, value)
Bildirimsel testlersdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
JSONPath sorgularısdk.jsonPath('$.data.id')
AES şifreleme / çözme$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
MD5 / SHA özetleri (imzalama)$hash.md5(...) / $hash.sha256(...) (hex döndürür, standart ve birlikte çalışabilir)
UUID$uuid.v4()
Dize base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Motor QuickJS'tir: tarayıcıdaki crypto.subtle yoktur ve crypto.getRandomValues bu motorda çalışmaz (geçirilen diziyi doldurmaz) — AES için $crypto, rastgelelik için crypto.randomUUID / $uuid kullanın. WebCrypto'ya uzanmayın. Tam imzalar ve uyarılar: Script API Referansı.


Script Kütüphanelerini Require() ile Yükleme​

Paylaşılan mantık, adım olarak eklemek yerine CommonJS tarzı require() ile de yüklenebilir. Anahtar her zaman @libs/<key>'dir ve şu sırayla çözülür:

  1. Script kütüphanesi tanımlayıcısı — tam eşleşme, yeniden adlandırmalarda stabil (önerilir)
  2. Script kütüphanesi adı — okunabilir, ancak kütüphaneyi yeniden adlandırmak referansı bozar (belirsiz yinelenen adlar atlanır)
  3. Yerleşik kütüphaneler — uygulamayla birlikte gelir

Yerleşik kütüphaneler​

AnahtarDışa açılanlarNotlar
@libs/base64encode(str) / decode(text)UTF-8 güvenli Base64 (Çince ve emoji güvenli); decode boşluğu yok sayar, geçersiz diziler Latin-1 olarak tutulur
@libs/hexencode(str) / decode(text)UTF-8 güvenli küçük harf hex; decode hex dışı karakterleri yok sayar, tek uzunluk fırlatır

İkisi de genel takma adlar olarak sunulur (base64.encode(...) / hex.encode(...)) — require size yalnızca açık içe aktarma tarzını verir.

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

Kendi script kütüphaneleriniz​

Yeniden kullanılabilir fonksiyonları bir script kütüphanesi olarak kaydedin (module.exports ile dışa aktarım, giriş fonksiyonu gerekmez) ve herhangi bir ön/son script'ten yükleyin:

// 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;
}
  • Stabil tanımlayıcı biçimi için kütüphane yöneticisindeki Copy require statement'ı kullanın.
  • Kütüphaneler başka kütüphaneleri require edebilir — tüm bağımlılık kapanışı otomatik paketlenir (döngüler Node tarzında çözülür, sonsuz döngü yok).
  • Modül önbelleği her çalıştırmada yeniden kurulur: kütüphaneler asla istekler arasında durum taşımaz.
  • Bir npm paketini yeniden kullanmak için önce tek dosyaya paketleyin (ör. esbuild --format=iife ya da Browserify/Webpack), dosyayı script kütüphanesi olarak içe aktarın, sonra require('@libs/<name>'). Node (Buffer/fs/crypto/process) ya da DOM bağımlılığı olmayan saf JS derlemelerini seçin.
  • Eksik anahtar Error: require: 未找到库 [...] fırlatır — gönderim öncesi hata isteği durdurur, yanıt sonrası hata orijinal yanıtı korur. Yorumların içindeki require çağrıları yok sayılır.

Tam require semantiği: Script API Referansı.


Birden Çok Script Nasıl İşbirliği Yapar​

Bir isteğin birkaç script'i olduğunda, onlar aynı globalThis'i paylaşır (doğrulandı). Böylece şunları yapabilirsiniz:

Faydalar: her script tek bir sorumluluğa sahiptir ve bağımsız açılıp kapatılabilir. Bir "kütüphane script'i" de tam bir script'tir (kendi onRequest/onResponse'u ile) — tüm zinciri çalıştırmak için adım olarak ekleyin, ya da içine module.exports ile saf fonksiyonlar koyun ve require('@libs/<key>') ile yükleyin (bkz. Script kütüphanelerini require() ile yükleme).

Somut zincir örnekleri için (token için login, AES round-trip) bkz. recipes.