Saltar al contenido principal

Scripts (visión de desarrollador)

Los scripts de envío previo / post-respuesta son la navaja suiza de Quick Request: firma dinámica, cifrado y descifrado, aserciones condicionales y paso de valores entre solicitudes viven aquí. Los scripts se escriben en JavaScript y se ejecutan en el motor QuickJS integrado.

Esta página cubre solo qué puedes añadir en la interfaz y qué pueden hacer los scripts; para las firmas completas de la API de JavaScript consulta la Referencia de la API de scripts.


Una solicitud tiene dos «cadenas de acciones»​

En la página del editor de solicitudes puedes añadir varios pasos a las cadenas de envío previo y de post-respuesta; se ejecutan en orden. Cada paso es uno de estos:

Tipo de pasoQué haces en la interfazUso típico
ScriptEscribes un fragmento de JavaScriptCambiar headers/body, firma, descifrado, lógica condicional
Script de bibliotecaReferencias un script compartido guardadoReutilizar «inyectar token», «logging unificado» en muchos sitios
ExtractTomas un valor de la respuesta y lo guardas como variablePasar el token de login a la siguiente solicitud
AssertAñades una validación sobre la respuestaCódigo de estado = 200, un campo existe
WaitPausas unos milisegundosLimitar tasa, intervalos de sondeo

Cómo escribir scripts: dos puntos de entrada​

El motor de scripts busca funciones de entrada conocidas en tu script:

// 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;
}
  • Escribe onRequest en la cadena de envío previo y onResponse en la de post-respuesta.
  • Los nombres de las funciones deben ser exactamente estos; de lo contrario el script se trata como «sin punto de entrada» y se omite.
  • Se admite await.

Qué pueden cambiar los scripts​

Cambiar la solicitud (el objeto request en onRequest)​

QuieresCómo
Establecer / sobrescribir una cabecerarequest.headers.set('Authorization', 'Bearer ' + tok)
Añadir / cambiar un query paramrequest.queries.set('ts', String(Date.now()))
Leer el cuerpo en crudovar text = request.body.parseText() o request.body.parseJSON()
Reescribir el cuerpo completorequest.body = the new string (asignación directa)

Leer / cambiar la respuesta (el objeto response en onResponse)​

QuieresCómo
Leer el código de estadoresponse.statusCode
Leer una cabecera de respuestaresponse.headers.get('Set-Cookie')
Leer el cuerporesponse.body.parseJSON() / .parseText()
Reescribir todo el cuerpo de la respuestaresponse.body = the new string — la vista de interfaz/resultado muestra el contenido reescrito (verificado)

Capacidades integradas — no reinventes la rueda​

Los scripts incluyen un lote de herramientas integradas (sdk.*) y capacidades nativas con prefijo $: cifrado, resúmenes, codificación, aleatoriedad y JSONPath están cubiertos:

CapacidadQué usar
Leer / escribir variables (paso entre solicitudes)sdk.env.get(name) / sdk.env.set(name, value)
Pruebas declarativassdk.test('el estado debería ser 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Consultas JSONPathsdk.jsonPath('$.data.id')
Cifrado / descifrado AES$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
Resúmenes MD5 / SHA (firma)$hash.md5(...) / $hash.sha256(...) (devuelve hex, estándar e interoperable)
UUID$uuid.v4()
base64 de cadenassdk.utils.base64Encode(str) / base64Decode(str)

⚠️ El motor es QuickJS: no existe el crypto.subtle del navegador y crypto.getRandomValues no funciona en este motor (no rellena el array que recibe) — usa $crypto para AES y crypto.randomUUID / $uuid para aleatoriedad. No recurras a WebCrypto. Firmas completas y matices: Referencia de la API de scripts.


Require de bibliotecas de scripts​

La lógica compartida también puede cargarse con require() al estilo CommonJS en lugar de añadirse como paso. La clave siempre es @libs/<key>, resuelta en este orden:

  1. Identificador de la biblioteca de scripts — coincidencia exacta, estable ante renombrados (recomendado)
  2. Nombre de la biblioteca de scripts — legible, pero renombrar la biblioteca rompe la referencia (los nombres duplicados ambiguos se omiten)
  3. Bibliotecas integradas — incluidas con la app

Bibliotecas integradas​

ClaveExportaNotas
@libs/base64encode(str) / decode(text)Base64 seguro con UTF-8 (chino y emoji seguros); decode ignora espacios en blanco, las secuencias inválidas se mantienen como Latin-1
@libs/hexencode(str) / decode(text)Hex en minúsculas seguro con UTF-8; decode ignora los caracteres no hex, la longitud impar lanza error

Ambas también se exponen como alias globales (base64.encode(...) / hex.encode(...)) — require solo te da el estilo de importación explícito.

const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'

Tus propias bibliotecas de scripts​

Guarda las funciones reutilizables como biblioteca de scripts (exporta vía module.exports, no necesita función de entrada) y requiérela desde cualquier script de envío previo / post-respuesta:

// 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;
}
  • Usa Copy require statement en el gestor de bibliotecas para obtener la forma de identificador estable.
  • Las bibliotecas pueden hacer require de otras bibliotecas — toda la dependencia se empaqueta automáticamente (los ciclos se resuelven al estilo Node, sin bucle infinito).
  • La caché de módulos se reconstruye en cada ejecución: las bibliotecas nunca conservan estado entre solicitudes.
  • Para reutilizar un paquete npm, empaquétalo primero en un único archivo (p. ej. esbuild --format=iife, o Browserify/Webpack), importa el archivo como biblioteca de scripts y luego require('@libs/<name>'). Elige builds de JS puro sin dependencias de Node (Buffer/fs/crypto/process) ni del DOM.
  • Una clave faltante lanza Error: require: 未找到库 [...] — los fallos de envío previo abortan la solicitud; los de post-respuesta conservan la respuesta original. Las llamadas a require dentro de comentarios se ignoran.

Semántica completa de require: Referencia de la API de scripts.


Cómo cooperan varios scripts​

Cuando una solicitud tiene varios scripts, comparten el mismo globalThis (verificado). Así puedes:

Ventajas: cada script tiene una única responsabilidad y puede activarse o desactivarse de forma independiente. Un «script de biblioteca» también es un script completo (con su propio onRequest/onResponse) — añádelo como paso para ejecutar toda la cadena, o guarda en él funciones puras con module.exports y cárgalas con require('@libs/<key>') (ver Require de bibliotecas de scripts).

Para ejemplos concretos encadenados (login para token, ida y vuelta AES) consulta recetas.