Aller au contenu principal

Scripts (vue développeur)

Les scripts de pré-envoi / post-réponse sont le couteau suisse de Quick Request : signature dynamique, chiffrement & déchiffrement, assertions conditionnelles et passage de valeurs entre requêtes vivent tous ici. Les scripts s'écrivent en JavaScript et tournent dans le moteur QuickJS intégré.

Cette page couvre uniquement ce que vous pouvez ajouter dans l'interface et ce que les scripts peuvent faire ; pour les signatures complètes de l'API JavaScript, voir la Référence de l'API de scripts.


Une requête a deux « chaînes d'actions »​

Sur la page d'édition d'une requête, vous pouvez ajouter plusieurs étapes aux chaînes de pré-envoi et de post-réponse ; elles s'exécutent dans l'ordre. Chaque étape est l'une des suivantes :

Type d'étapeCe qu'on fait dans l'interfaceUsage typique
ScriptÉcrire un morceau de JavaScriptModifier headers/body, signer, déchiffrer, logique conditionnelle
Script de bibliothèqueRéférencer un script partagé enregistréRéutiliser « injection du token », « journalisation unifiée » à de nombreux endroits
ExtractionPrendre une valeur de la réponse et la stocker en variableTransmettre le token de login à la requête suivante
AssertionAjouter une validation sur la réponseCode de statut = 200, un champ existe
AttenteMarquer une pause de quelques millisecondesLimitation de débit, intervalles de polling

Comment écrire un script : deux points d'entrée​

Le moteur de script cherche des fonctions d'entrée bien connues dans votre 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;
}
  • Écrivez onRequest dans la chaîne de pré-envoi, onResponse dans la chaîne de post-réponse.
  • Les noms de fonctions doivent être exactement ceux-ci, sinon le script est traité comme « sans point d'entrée » et ignoré.
  • await est pris en charge.

Ce que les scripts peuvent changer​

Modifier la requête (l'objet request dans onRequest)​

Vous voulezComment
Définir / remplacer un headerrequest.headers.set('Authorization', 'Bearer ' + tok)
Ajouter / modifier un query paramrequest.queries.set('ts', String(Date.now()))
Lire le body brutvar text = request.body.parseText() ou request.body.parseJSON()
Réécrire tout le bodyrequest.body = the new string (affectation simple)

Lire / modifier la réponse (l'objet response dans onResponse)​

Vous voulezComment
Lire le code de statutresponse.statusCode
Lire un header de réponseresponse.headers.get('Set-Cookie')
Lire le bodyresponse.body.parseJSON() / .parseText()
Réécrire tout le body de la réponseresponse.body = the new string — la vue interface/résultat montre le contenu réécrit (vérifié)

Capacités intégrées — nul besoin de réinventer​

Les scripts sont livrés avec un lot d'outils intégrés (sdk.*) et des capacités natives préfixées $ : chiffrement, empreintes, encodage, aléatoire et JSONPath sont tous couverts :

CapacitéQuoi utiliser
Lire / écrire des variables (passage entre requêtes)sdk.env.get(name) / sdk.env.set(name, value)
Tests déclaratifssdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Requêtes JSONPathsdk.jsonPath('$.data.id')
Chiffrement / déchiffrement AES$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
Empreintes MD5 / SHA (signature)$hash.md5(...) / $hash.sha256(...) (renvoie de l'hex, standard et interopérable)
UUID$uuid.v4()
Base64 de chaînessdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Le moteur est QuickJS : pas de crypto.subtle de navigateur, et crypto.getRandomValues ne fonctionne pas dans ce moteur (il ne remplit pas le tableau passé) — utilisez $crypto pour l'AES, et crypto.randomUUID / $uuid pour l'aléatoire. N'allez pas chercher WebCrypto. Signatures et pièges complets : Référence de l'API de scripts.


Require de bibliothèques de scripts​

La logique partagée peut aussi être chargée avec un require() façon CommonJS au lieu d'être ajoutée comme étape. La clé est toujours @libs/<key>, résolue dans cet ordre :

  1. Identifiant de bibliothèque de scripts — correspondance exacte, stable lors des renommages (recommandé)
  2. Nom de bibliothèque de scripts — lisible, mais renommer la bibliothèque casse la référence (les noms dupliqués ambigus sont ignorés)
  3. Bibliothèques intégrées — livrées avec l'app

Bibliothèques intégrées​

CléExportsNotes
@libs/base64encode(str) / decode(text)Base64 sûr UTF-8 (chinois et emoji ok) ; decode ignore les espaces, les séquences invalides sont gardées en Latin-1
@libs/hexencode(str) / decode(text)Hex minuscule sûr UTF-8 ; decode ignore les caractères non hex, longueur impaire → exception

Les deux sont aussi exposés comme alias globaux (base64.encode(...) / hex.encode(...)) — require offre simplement le style d'import explicite.

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

Vos propres bibliothèques de scripts​

Enregistrez les fonctions réutilisables dans une bibliothèque de scripts (export via module.exports, aucune fonction d'entrée nécessaire) et requirez-la depuis n'importe quel script 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;
}
  • Utilisez Copier l'instruction require dans le gestionnaire de bibliothèques pour obtenir la forme à identifiant stable.
  • Les bibliothèques peuvent require d'autres bibliothèques — toute la fermeture de dépendances est bundlée automatiquement (les cycles se résolvent façon Node, pas de boucle infinie).
  • Le cache de modules est reconstruit à chaque exécution : les bibliothèques ne portent jamais d'état d'une requête à l'autre.
  • Pour réutiliser un package npm, bundlez-le d'abord en un seul fichier (ex. esbuild --format=iife, ou Browserify/Webpack), importez ce fichier comme bibliothèque de scripts, puis require('@libs/<name>'). Choisissez des builds JS purs sans dépendances Node (Buffer/fs/crypto/process) ni DOM.
  • Une clé manquante lève Error: require: 未找到库 [...] — un échec en pré-envoi interrompt la requête, un échec en post-réponse conserve la réponse d'origine. Les appels require dans les commentaires sont ignorés.

Sémantique complète de require : Référence de l'API de scripts.


Comment plusieurs scripts coopèrent​

Quand une requête a plusieurs scripts, ils partagent le même globalThis (vérifié). Vous pouvez donc :

Avantages : chaque script a une seule responsabilité et peut être activé/désactivé indépendamment. Un « script de bibliothèque » est aussi un script complet (avec ses propres onRequest/onResponse) — ajoutez-le comme étape pour exécuter toute la chaîne, ou gardez-y des fonctions pures avec module.exports et chargez-les avec require('@libs/<key>') (voir Require de bibliothèques de scripts).

Pour des exemples concrets enchaînés (login pour token, aller-retour AES), voir recettes.