Перейти к основному содержимому

Scripting (глазами разработчика)

Скрипты перед отправкой / после ответа — швейцарский нож Quick Request: динамическая подпись, шифрование и расшифровка, условные проверки и передача значений между запросами живут здесь. Скрипты пишутся на JavaScript и выполняются во встроенном движке QuickJS.

Эта страница покрывает только что можно добавить в UI и что могут скрипты; полные сигнатуры JavaScript API смотрите в Справочнике API скриптов.


У одного запроса две «цепочки действий»​

На странице редактора запроса можно добавить несколько шагов в цепочки перед отправкой и после ответа; они выполняются по порядку. Каждый шаг — один из типов:

Тип шагаЧто вы делаете в UIТипичное применение
СкриптПишете фрагмент JavaScriptИзменение headers/body, подпись, расшифровка, условная логика
Библиотечный скриптСсылаетесь на сохраненный общий скриптПереиспользование «внедрения токена», «единого логирования» во многих местах
ИзвлечениеБерете значение из ответа и сохраняете как переменнуюПередать токен входа следующему запросу
ПроверкаДобавляете одну валидацию к ответуКод состояния = 200, поле существует
ОжиданиеПауза на несколько миллисекундRate limiting, интервалы опроса

Как писать скрипты: две точки входа​

Движок скриптов ищет в вашем скрипте известные функции входа:

// 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()))
Прочитать сырое телоvar text = request.body.parseText() или request.body.parseJSON()
Переписать все телоrequest.body = the new string (простое присваивание)

Чтение / изменение ответа (объект response в onResponse)​

Вы хотитеКак
Прочитать код состоянияresponse.statusCode
Прочитать заголовок ответаresponse.headers.get('Set-Cookie')
Прочитать телоresponse.body.parseJSON() / .parseText()
Переписать все тело ответа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 не работает в этом движке (не заполняет переданный массив) — используйте $crypto для AES, а crypto.randomUUID / $uuid для случайности. Не тянитесь к WebCrypto. Полные сигнатуры и оговорки: Справочник API скриптов.


Подключение библиотек скриптов​

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

  1. Идентификатор библиотеки скриптов — точное совпадение, стабилен при переименованиях (рекомендуется)
  2. Имя библиотеки скриптов — читаемо, но переименование библиотеки ломает ссылку (неоднозначные дубликаты пропускаются)
  3. Встроенные библиотеки — поставляются с приложением

Встроенные библиотеки​

КлючExportsПримечания
@libs/base64encode(str) / decode(text)Base64, безопасный для UTF-8 (китайский и emoji OK); decode игнорирует whitespace, неверные последовательности сохраняются как 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, функция входа не нужна) и подключайте из любого скрипта pre/post:

// 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: Справочник API скриптов.


Как сотрудничают несколько скриптов​

Когда у запроса несколько скриптов, они разделяют один globalThis (проверено). Поэтому можно:

Преимущества: у каждого скрипта одна ответственность, каждый можно включать/выключать независимо. «Библиотечный скрипт» — тоже полный скрипт (со своим onRequest/onResponse) — добавьте его шагом, чтобы выполнить всю цепочку, или храните в нем чистые функции с module.exports и загружайте через require('@libs/<key>') (см. Подключение библиотек скриптов).

Конкретные цепочечные примеры (вход за токеном, AES-круг) смотрите в recipes.