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 paso | Qué haces en la interfaz | Uso típico |
|---|---|---|
| Script | Escribes un fragmento de JavaScript | Cambiar headers/body, firma, descifrado, lógica condicional |
| Script de biblioteca | Referencias un script compartido guardado | Reutilizar «inyectar token», «logging unificado» en muchos sitios |
| Extract | Tomas un valor de la respuesta y lo guardas como variable | Pasar el token de login a la siguiente solicitud |
| Assert | Añades una validación sobre la respuesta | Código de estado = 200, un campo existe |
| Wait | Pausas unos milisegundos | Limitar 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
onRequesten la cadena de envío previo yonResponseen 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)
| Quieres | Cómo |
|---|---|
| Establecer / sobrescribir una cabecera | request.headers.set('Authorization', 'Bearer ' + tok) |
| Añadir / cambiar un query param | request.queries.set('ts', String(Date.now())) |
| Leer el cuerpo en crudo | var text = request.body.parseText() o request.body.parseJSON() |
| Reescribir el cuerpo completo | request.body = the new string (asignación directa) |
Leer / cambiar la respuesta (el objeto response en onResponse)
| Quieres | Cómo |
|---|---|
| Leer el código de estado | response.statusCode |
| Leer una cabecera de respuesta | response.headers.get('Set-Cookie') |
| Leer el cuerpo | response.body.parseJSON() / .parseText() |
| Reescribir todo el cuerpo de la respuesta | response.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:
| Capacidad | Qué usar |
|---|---|
| Leer / escribir variables (paso entre solicitudes) | sdk.env.get(name) / sdk.env.set(name, value) |
| Pruebas declarativas | sdk.test('el estado debería ser 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Consultas JSONPath | sdk.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 cadenas | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ El motor es QuickJS: no existe el
crypto.subtledel navegador ycrypto.getRandomValuesno funciona en este motor (no rellena el array que recibe) — usa$cryptopara AES ycrypto.randomUUID/$uuidpara 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:
- Identificador de la biblioteca de scripts — coincidencia exacta, estable ante renombrados (recomendado)
- Nombre de la biblioteca de scripts — legible, pero renombrar la biblioteca rompe la referencia (los nombres duplicados ambiguos se omiten)
- Bibliotecas integradas — incluidas con la app
Bibliotecas integradas
| Clave | Exporta | Notas |
|---|---|---|
@libs/base64 | encode(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/hex | encode(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
requirede 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 luegorequire('@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 arequiredentro 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.