Lewati ke konten utama

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 langkahApa yang Anda lakukan di UIPenggunaan tipikal
SkripMenulis sepotong JavaScriptMengubah headers/body, signing, dekripsi, logika kondisional
Skrip pustakaMereferensikan skrip bersama yang tersimpanMenggunakan ulang "injeksi token", "logging terpadu" di banyak tempat
EkstrakMengambil nilai dari respons dan menyimpannya sebagai variabelMeneruskan token login ke permintaan berikutnya
AssertionMenambahkan satu validasi terhadap responsKode status = 200, sebuah bidang ada
TungguBerhenti sejenak selama beberapa milidetikPembatasan 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 onRequest di rantai pra-kirim, onResponse di rantai pasca-respons.
  • Nama fungsi harus persis seperti ini, jika tidak skrip dianggap "tidak ada entry point" dan dilewati.
  • await didukung.

Apa yang Dapat Diubah Skrip​

Mengubah permintaan (objek request dalam onRequest)​

Anda inginCaranya
Mengatur / menimpa headerrequest.headers.set('Authorization', 'Bearer ' + tok)
Menambah / mengubah query paramrequest.queries.set('ts', String(Date.now()))
Membaca body mentahvar text = request.body.parseText() atau request.body.parseJSON()
Menulis ulang seluruh bodyrequest.body = the new string (penugasan biasa)

Membaca / mengubah respons (objek response dalam onResponse)​

Anda inginCaranya
Membaca kode statusresponse.statusCode
Membaca header responsresponse.headers.get('Set-Cookie')
Membaca bodyresponse.body.parseJSON() / .parseText()
Menulis ulang seluruh body responsresponse.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:

KemampuanYang dipakai
Membaca / menulis variabel (penerusan lintas permintaan)sdk.env.get(name) / sdk.env.set(name, value)
Tes deklaratifsdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Kueri JSONPathsdk.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 stringsdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Engine-nya QuickJS: tidak ada crypto.subtle milik browser, dan crypto.getRandomValues tidak bekerja di engine ini (tidak mengisi array yang diberikan) — gunakan $crypto untuk AES, dan crypto.randomUUID / $uuid untuk 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:

  1. Identifier pustaka skrip — kecocokan persis, stabil lintas penggantian nama (direkomendasikan)
  2. Nama pustaka skrip — mudah dibaca, tetapi mengganti nama pustaka memutus referensinya (nama duplikat ambigu dilewati)
  3. Pustaka bawaan — dibundel bersama aplikasi

Pustaka bawaan​

KeyEksporCatatan
@libs/base64encode(str) / decode(text)Base64 aman-UTF-8 (Mandarin & emoji aman); decode mengabaikan spasi, urutan tidak valid dipertahankan sebagai Latin-1
@libs/hexencode(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 require pustaka 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, lalu require('@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. Panggilan require di 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.