Scripting (Perspektif Pengembang)
Skrip pra-kirim / pasca-respons adalah pisau serbaguna Quick Request: signing dinamis, enkripsi & dekripsi, assertion kondisional, dan penerusan nilai lintas permintaan semuanya ada di sini. Skrip ditulis dalam JavaScript dan berjalan di engine QuickJS bawaan.
Halaman ini hanya membahas apa yang bisa Anda tambahkan di UI dan apa yang bisa dilakukan skrip; untuk signature API JavaScript lengkap lihat Referensi Script API.
Satu Permintaan Memiliki Dua "Rantai Aksi"
Di halaman editor permintaan Anda dapat menambahkan beberapa langkah ke rantai pra-kirim dan pasca-respons; semuanya berjalan sesuai urutan. Setiap langkah adalah salah satu dari:
| Tipe langkah | Apa yang Anda lakukan di UI | Penggunaan tipikal |
|---|---|---|
| Skrip | Menulis sepotong JavaScript | Mengubah headers/body, signing, dekripsi, logika kondisional |
| Skrip pustaka | Mereferensikan skrip bersama yang tersimpan | Menggunakan ulang "injeksi token", "logging terpadu" di banyak tempat |
| Ekstrak | Mengambil nilai dari respons dan menyimpannya sebagai variabel | Meneruskan token login ke permintaan berikutnya |
| Assertion | Menambahkan satu validasi terhadap respons | Kode status = 200, sebuah bidang ada |
| Tunggu | Berhenti sejenak selama beberapa milidetik | Pembatasan laju, interval polling |
Cara Menulis Skrip: Dua Entry Point
Engine skrip mencari fungsi masuk (entry function) yang dikenal dalam skrip Anda:
// 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;
}
- Tulis
onRequestdi rantai pra-kirim,onResponsedi rantai pasca-respons. - Nama fungsi harus persis seperti ini, jika tidak skrip dianggap "tidak ada entry point" dan dilewati.
awaitdidukung.
Apa yang Dapat Diubah Skrip
Mengubah permintaan (objek request dalam onRequest)
| Anda ingin | Caranya |
|---|---|
| Mengatur / menimpa header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Menambah / mengubah query param | request.queries.set('ts', String(Date.now())) |
| Membaca body mentah | var text = request.body.parseText() atau request.body.parseJSON() |
| Menulis ulang seluruh body | request.body = the new string (penugasan biasa) |
Membaca / mengubah respons (objek response dalam onResponse)
| Anda ingin | Caranya |
|---|---|
| Membaca kode status | response.statusCode |
| Membaca header respons | response.headers.get('Set-Cookie') |
| Membaca body | response.body.parseJSON() / .parseText() |
| Menulis ulang seluruh body respons | response.body = the new string — tampilan UI/hasil menunjukkan konten yang ditulis ulang (terverifikasi) |
Kemampuan Bawaan — Tidak Perlu Membuat Ulang
Skrip dilengkapi sejumlah alat bawaan (sdk.*) dan kemampuan native berawalan $: enkripsi, digest, encoding, keacakan, dan JSONPath semuanya tercakup:
| Kemampuan | Yang dipakai |
|---|---|
| Membaca / menulis variabel (penerusan lintas permintaan) | sdk.env.get(name) / sdk.env.set(name, value) |
| Tes deklaratif | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Kueri JSONPath | sdk.jsonPath('$.data.id') |
| Enkripsi / dekripsi AES | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| Digest MD5 / SHA (signing) | $hash.md5(...) / $hash.sha256(...) (mengembalikan hex, standar & interoperabel) |
| UUID | $uuid.v4() |
| Base64 string | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Engine-nya QuickJS: tidak ada
crypto.subtlemilik browser, dancrypto.getRandomValuestidak bekerja di engine ini (tidak mengisi array yang diberikan) — gunakan$cryptountuk AES, dancrypto.randomUUID/$uuiduntuk keacakan. Jangan mencoba WebCrypto. Signature lengkap dan catatannya: Referensi Script API.
Memuat Pustaka Skrip dengan require()
Logika bersama juga dapat dimuat dengan require() bergaya CommonJS alih-alih ditambahkan sebagai langkah. Key-nya selalu @libs/<key>, diselesaikan dengan urutan ini:
- Identifier pustaka skrip — kecocokan persis, stabil lintas penggantian nama (direkomendasikan)
- Nama pustaka skrip — mudah dibaca, tetapi mengganti nama pustaka memutus referensinya (nama duplikat ambigu dilewati)
- Pustaka bawaan — dibundel bersama aplikasi
Pustaka bawaan
| Key | Ekspor | Catatan |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | Base64 aman-UTF-8 (Mandarin & emoji aman); decode mengabaikan spasi, urutan tidak valid dipertahankan sebagai Latin-1 |
@libs/hex | encode(str) / decode(text) | Hex huruf kecil aman-UTF-8; decode mengabaikan karakter non-hex, panjang ganjil melempar error |
Keduanya juga diekspos sebagai alias global (base64.encode(...) / hex.encode(...)) — require hanya memberi Anda gaya impor yang eksplisit.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Pustaka skrip milik Anda sendiri
Simpan fungsi yang dapat digunakan ulang sebagai pustaka skrip (ekspor via module.exports, tidak perlu fungsi masuk) dan require dari skrip pra/pasca mana pun:
// 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;
}
- Gunakan Copy require statement di pengelola pustaka untuk mendapatkan bentuk identifier yang stabil.
- Pustaka boleh
requirepustaka lain — seluruh closure dependensi dibundel otomatis (siklus diselesaikan gaya Node, tanpa loop tak berujung). - Cache modul dibangun ulang pada setiap eksekusi: pustaka tidak pernah membawa state lintas permintaan.
- Untuk memakai paket npm, bundel dulu menjadi satu file (mis.
esbuild --format=iife, atau Browserify/Webpack), impor file itu sebagai pustaka skrip, lalurequire('@libs/<name>'). Pilih build JS murni tanpa dependensi Node (Buffer/fs/crypto/process) atau DOM. - Key yang hilang melempar
Error: require: 未找到库 [...]— kegagalan pra-kirim membatalkan permintaan, kegagalan pasca-respons mempertahankan respons asli. Panggilanrequiredi dalam komentar diabaikan.
Semantik require lengkap: Referensi Script API.
Cara Beberapa Skrip Bekerja Sama
Ketika sebuah permintaan memiliki beberapa skrip, semuanya berbagi globalThis yang sama (terverifikasi). Jadi Anda dapat:
Manfaat: setiap skrip punya satu tanggung jawab dan dapat diaktifkan/dinonaktifkan secara independen. "Skrip pustaka" juga adalah skrip lengkap (dengan onRequest/onResponse miliknya sendiri) — tambahkan sebagai langkah untuk menjalankan seluruh rantai, atau simpan fungsi murni di dalamnya dengan module.exports dan muat dengan require('@libs/<key>') (lihat Pustaka Skrip require).
Untuk contoh rantai konkret (login untuk token, bolak-balik AES) lihat resep.