Scripting (Погляд розробника)
Скрипти перед відправленням / після відповіді — швейцарський ніж Quick Request: динамічне підписування, шифрування й розшифрування, умовні assertions та передавання значень між запитами живуть тут. Скрипти пишуться JavaScript і виконуються у вбудованому рушії QuickJS.
Ця сторінка охоплює лише що можна додати в UI і що можуть скрипти; повні сигнатури JavaScript API дивіться у Довіднику Script API.
Один запит має два «Ланцюжки дій»
На сторінці редагування запиту можна додати кілька кроків до ланцюжків перед відправленням та після відповіді; вони виконуються за порядком. Кожен крок — один із:
| Тип кроку | Що робите в UI | Типове використання |
|---|---|---|
| Скрипт | Пишете шматок JavaScript | Зміна заголовків/body, підписування, розшифрування, умовна логіка |
| Бібліотечний скрипт | Посилаєтеся на збережений спільний скрипт | Повторне використання «ін'єкції токена», «уніфікованого логування» в багатьох місцях |
| Витягування | Берете значення з відповіді та зберігаєте як змінну | П ередача токена входу наступному запиту |
| Assert | Додаєте одну перевірку відповіді | Код статусу = 200, поле існує |
| Очікування | Пауза на кілька мілісекунд | Обмеження швидкості, інтервали опитування |
Як писати скрипти: дві точки входу
Рушій скриптів шукає відомі функції входу у вашому скрипті:
// 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у ланцюжку перед відправленням,onResponse— у ланцюжку після відповіді. - Назви функцій мають бути точно такими, інакше скрипт вважається «без точки входу» і пропускається.
awaitпідтримується.
Що можуть змінювати скрипти
Зміна запиту (об'єкт request в onRequest)
| Ви хочете | Як |
|---|---|
| Встановити / перевизначити заголовок | request.headers.set('Authorization', 'Bearer ' + tok) |
| Д одати / змінити query параметр | request.queries.set('ts', String(Date.now())) |
| Прочитати сирий body | var text = request.body.parseText() або request.body.parseJSON() |
| Переписати весь body | request.body = the new string (просте присвоєння) |
Читання / зміна відповіді (об'єкт response в onResponse)
| Ви хочете | Як |
|---|---|
| Прочитати код статусу | response.statusCode |
| Прочитати заголовок відповіді | response.headers.get('Set-Cookie') |
| Прочитати body | response.body.parseJSON() / .parseText() |
| Переписати весь body відповіді | response.body = the new string — UI/подання результату показує перезаписаний вміст (перевірено) |
Вбудовані можливості — не вигадуйте велосипед
Скрипти постачаються з набором вбудованих інструментів (sdk.*) та нативними можливостями з префіксом $: шифрування, дайджести, кодування, випадковість і JSONPath — усе покрито:
| Можливість | Що використовувати |
|---|---|
| Читання / запис змінних (передача між запитами) | sdk.env.get(name) / sdk.env.set(name, value) |
| Декларативні тести | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| JSONPath запити | sdk.jsonPath('$.data.id') |
| AES шифрування / розшифрування | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| MD5 / SHA дайджести (підписування) | $hash.md5(...) / $hash.sha256(...) (повертає hex, стандартний і сумісний) |
| UUID | $uuid.v4() |
| Рядковий base64 | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Рушій — QuickJS: немає браузерного
crypto.subtle, аcrypto.getRandomValuesне працює в цьому рушії (не заповнює переданий масив) — для AES використовуйте$crypto, для випадковості —crypto.randomUUID/$uuid. Не тягніться до WebCrypto. Повні сигнатури та застереження: Довідник Script API.
Завантаження бібліотек скриптів через require()
Спільну логіку можна також завантажувати через require() у стилі CommonJS замість додавання як крок. Ключ завжди @libs/<key>, розв'язується в такому порядку:
- Ідентифікатор бібліотеки скриптів — точний збіг, стабільний під час перейменувань (рекомендовано)
- Назва бібліотеки скриптів — читабельна, але перейменування бібліотеки ламає посилання (двозначні дублікати назв пропускаються)
- Вбудовані бібліотеки — постачаються з застосунком
Вбудовані бібліотеки
| Ключ | Експортує | Примітки |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | Base64, безпечний для UTF-8 (не-ASCII текст та емодзі в порядку); decode ігнорує пробіли, недійсні послідовності лишаються як Latin-1 |
@libs/hex | encode(str) / decode(text) | Нижній регістр hex, безпечний для UTF-8; decode ігнорує не-hex символи, непарна довжина кидає виняток |
Обидві також доступні як глобальні аліаси (base64.encode(...) / hex.encode(...)) — require просто дає вам явний стиль імпорту.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Власні бібліотеки скриптів
Зберігайте перевикористовувані функції як бібліотеку скриптів (експорт через module.exports, функція входу не потрібна) і завантажуйте її з будь-якого скрипта перед/після:
// 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;
}
- Використовуйте Copy require statement у менеджері бібліотек, щоб отримати стабільну форму з ідентифікатором.
- Бібліотеки можуть
requireити інші бібліотеки — уся замкнена множина залежностей пакується автоматично (цикли розв'язуються у стилі Node, без нескінченного циклу). - Кеш модулів перебудовується на кожному виконанні: бібліотеки ніколи не переносять стан між запитами.
- Щоб перевикористати npm-пакет, спочатку запакуйте його в один файл (наприклад
esbuild --format=iife, або Browserify/Webpack), імпортуйте файл як бібліотеку скриптів, потімrequire('@libs/<name>'). Обирайте чисто-JS збірки без Node (Buffer/fs/crypto/process) або DOM-залежностей. - Відсутній ключ кидає
Error: require: 未找到库 [...]— невдача перед відправленням перериває запит, невдача після відповіді лишає початкову відповідь. Викликиrequireвсередині коментарів ігноруються.
Повна семантика require: Довідник Script API.
Як кілька скриптів співпрацюють
Коли запит має кілька скриптів, вони спільно використовують той самий globalThis (перевірено). Тож можна:
Переваги: кожен скрипт має одну відповідальність і може вмикатися незалежно. «Бібліотечний скрипт» теж повноцінний скрипт (з власним onRequest/onResponse) — додайте його як крок, щоб виконати весь ланцюжок, або тримайте в ньому чисті функції з module.exports і завантажуйте через require('@libs/<key>') (див. Завантаження бібліотек скриптів).
Конкретні приклади ланцюжків (вхід за токеном, AES round-trip) дивіться в recipes.