Перейти до основного вмісту

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()))
Прочитати сирий bodyvar text = request.body.parseText() або request.body.parseJSON()
Переписати весь bodyrequest.body = the new string (просте присвоєння)

Читання / зміна відповіді (об'єкт response в onResponse)​

Ви хочетеЯк
Прочитати код статусуresponse.statusCode
Прочитати заголовок відповідіresponse.headers.get('Set-Cookie')
Прочитати bodyresponse.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()
Рядковий base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Рушій — QuickJS: немає браузерного crypto.subtle, а crypto.getRandomValues не працює в цьому рушії (не заповнює переданий масив) — для AES використовуйте $crypto, для випадковості — crypto.randomUUID / $uuid. Не тягніться до WebCrypto. Повні сигнатури та застереження: Довідник Script API.


Завантаження бібліотек скриптів через require()​

Спільну логіку можна також завантажувати через require() у стилі CommonJS замість додавання як крок. Ключ завжди @libs/<key>, розв'язується в такому порядку:

  1. Ідентифікатор бібліотеки скриптів — точний збіг, стабільний під час перейменувань (рекомендовано)
  2. Назва бібліотеки скриптів — читабельна, але перейменування бібліотеки ламає посилання (двозначні дублікати назв пропускаються)
  3. Вбудовані бібліотеки — постачаються з застосунком

Вбудовані бібліотеки​

КлючЕкспортуєПримітки
@libs/base64encode(str) / decode(text)Base64, безпечний для UTF-8 (не-ASCII текст та емодзі в порядку); decode ігнорує пробіли, недійсні послідовності лишаються як Latin-1
@libs/hexencode(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.