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'étape | Ce qu'on fait dans l'interface | Usage typique |
|---|---|---|
| Script | Écrire un morceau de JavaScript | Modifier headers/body, signer, déchiffrer, logique conditionnelle |
| Script de bibliothèque | Référencer un script partagé enregistré | Réutiliser « injection du token », « journalisation unifiée » à de nombreux endroits |
| Extraction | Prendre une valeur de la réponse et la stocker en variable | Transmettre le token de login à la requête suivante |
| Assertion | Ajouter une validation sur la réponse | Code de statut = 200, un champ existe |
| Attente | Marquer une pause de quelques millisecondes | Limitation 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
onRequestdans la chaîne de pré-envoi,onResponsedans 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é.
awaitest pris en charge.
Ce que les scripts peuvent changer
Modifier la requête (l'objet request dans onRequest)
| Vous voulez | Comment |
|---|---|
| Définir / remplacer un header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Ajouter / modifier un query param | request.queries.set('ts', String(Date.now())) |
| Lire le body brut | var text = request.body.parseText() ou request.body.parseJSON() |
| Réécrire tout le body | request.body = the new string (affectation simple) |
Lire / modifier la réponse (l'objet response dans onResponse)
| Vous voulez | Comment |
|---|---|
| Lire le code de statut | response.statusCode |
| Lire un header de réponse | response.headers.get('Set-Cookie') |
| Lire le body | response.body.parseJSON() / .parseText() |
| Réécrire tout le body de la réponse | response.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éclaratifs | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Requêtes JSONPath | sdk.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înes | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Le moteur est QuickJS : pas de
crypto.subtlede navigateur, etcrypto.getRandomValuesne fonctionne pas dans ce moteur (il ne remplit pas le tableau passé) — utilisez$cryptopour l'AES, etcrypto.randomUUID/$uuidpour 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 :
- Identifiant de bibliothèque de scripts — correspondance exacte, stable lors des renommages (recommandé)
- 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)
- Bibliothèques intégrées — livrées avec l'app
Bibliothèques intégrées
| Clé | Exports | Notes |
|---|---|---|
@libs/base64 | encode(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/hex | encode(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
required'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, puisrequire('@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 appelsrequiredans 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.