Scripting (visão do desenvolvedor)
Os scripts de pré-envio / pós-resposta são o canivete suíço do Quick Request: assinatura dinâmica, criptografia e descriptografia, asserções condicionais e passagem de valores entre requisições vivem aqui. Os scripts são escritos em JavaScript e rodam no motor QuickJS integrado.
Esta página cobre apenas o que você pode adicionar na UI e o que os scripts podem fazer; para a lista completa de assinaturas da API JavaScript, veja a Referência da API de scripts.
Uma requisição tem duas 'cadeias de ações'
Na página do editor de requisição você pode adicionar várias etapas às cadeias de pré-envio e pós-resposta; elas rodam em ordem. Cada etapa é um dos tipos:
| Tipo de etapa | O que você faz na UI | Uso típico |
|---|---|---|
| Script | Escreve um trecho de JavaScript | Mudar headers/body, assinatura, descriptografia, lógica condicional |
| Script de biblioteca | Referencia um script compartilhado salvo | Reutilizar 'injetar token', 'logging unificado' em vários lugares |
| Extração | Pega um valor da resposta e armazena como variável | Passar o token de login para a próxima requisição |
| Asserção | Adiciona uma validação contra a resposta | Código de status = 200, um campo existe |
| Espera | Pausa por alguns milissegundos | Rate limiting, intervalos de polling |
Como escrever scripts: dois pontos de entrada
O motor de scripts procura funções de entrada conhecidas no seu 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;
}
- Escreva
onRequestna cadeia de pré-envio,onResponsena cadeia pós-resposta. - Os nomes das funções devem ser exatamente esses, senão o script é tratado como 'sem ponto de entrada' e pulado.
awaité suportado.
O que os scripts podem mudar
Mudando a requisição (o objeto request no onRequest)
| Você quer | Como |
|---|---|
| Definir / sobrescrever um header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Adicionar / mudar um query param | request.queries.set('ts', String(Date.now())) |
| Ler o corpo bruto | var text = request.body.parseText() ou request.body.parseJSON() |
| Reescrever o corpo inteiro | request.body = the new string (atribuição simples) |
Lendo / mudando a resposta (o objeto response no onResponse)
| Você quer | Como |
|---|---|
| Ler o código de status | response.statusCode |
| Ler um header da resposta | response.headers.get('Set-Cookie') |
| Ler o corpo | response.body.parseJSON() / .parseText() |
| Reescrever o corpo inteiro da resposta | response.body = the new string — a visão de resultado da UI mostra o conteúdo reescrito (verificado) |
Capacidades integradas — não precisa reinventar
Os scripts vêm com um conjunto de ferramentas integradas (sdk.*) e capacidades nativas prefixadas com $: criptografia, digests, codificação, aleatoriedade e JSONPath estão todos cobertos:
| Capacidade | O que usar |
|---|---|
| Ler / escrever variáveis (passagem entre requisições) | sdk.env.get(name) / sdk.env.set(name, value) |
| Testes declarativos | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Consultas JSONPath | sdk.jsonPath('$.data.id') |
| Criptografia / descriptografia AES | $crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv]) |
| Digests MD5 / SHA (assinatura) | $hash.md5(...) / $hash.sha256(...) (retorna hex, padrão e interoperável) |
| UUID | $uuid.v4() |
| Base64 de string | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ O motor é QuickJS: não existe
crypto.subtlede browser, ecrypto.getRandomValuesnão funciona neste motor (não preenche o array passado) — use$cryptopara AES, ecrypto.randomUUID/$uuidpara aleatoriedade. Não recorra ao WebCrypto. Assinaturas completas e ressalvas: Referência da API de scripts.
Require de bibliotecas de scripts
Lógica compartilhada também pode ser carregada com require() no estilo CommonJS em vez de ser adicionada como etapa. A chave é sempre @libs/<key>, resolvida nesta ordem:
- Identificador da biblioteca de scripts — correspondência exata, estável entre renomeações (recomendado)
- Nome da biblioteca de scripts — legível, mas renomear a biblioteca quebra a referência (nomes duplicados ambíguos são pulados)
- Bibliotecas integradas — empacotadas com o app
Bibliotecas integradas
| Chave | Exports | Notas |
|---|---|---|
@libs/base64 | encode(str) / decode(text) | Base64 seguro para UTF-8 (chinês e emoji OK); decode ignora whitespace, sequências inválidas mantidas como Latin-1 |
@libs/hex | encode(str) / decode(text) | Hex minúsculo seguro para UTF-8; decode ignora caracteres não-hex, comprimento ímpar lança erro |
Ambas também são expostas como aliases globais (base64.encode(...) / hex.encode(...)) — o require apenas dá o estilo de importação explícito.
const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'
Suas próprias bibliotecas de scripts
Salve funções reutilizáveis como uma biblioteca de scripts (export via module.exports, sem função de entrada necessária) e faça require dela de qualquer script pré/pós:
// 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;
}
- Use Copy require statement no gerenciador de bibliotecas para obter a forma estável de identificador.
- Bibliotecas podem fazer
requirede outras bibliotecas — todo o fechamento de dependências é empacotado automaticamente (ciclos resolvem ao estilo Node, sem loop infinito). - O cache de módulos é reconstruído a cada execução: bibliotecas nunca carregam estado entre requisições.
- Para reutilizar um pacote npm, empacote-o primeiro em um único arquivo (ex.:
esbuild --format=iife, ou Browserify/Webpack), importe o arquivo como biblioteca de scripts e depoisrequire('@libs/<name>'). Escolha builds JS puros sem dependências de Node (Buffer/fs/crypto/process) ou de DOM. - Uma chave ausente lança
Error: require: 未找到库 [...]— falhas de pré-envio abortam a requisição, falhas de pós-resposta mantêm a resposta original. Chamadasrequiredentro de comentários são ignoradas.
Semântica completa do require: Referência da API de scripts.
Como múltiplos scripts cooperam
Quando uma requisição tem vários scripts, eles compartilham o mesmo globalThis (verificado). Então você pode:
Vantagens: cada script tem uma única responsabilidade e pode ser ativado/desativado independentemente. Um 'script de biblioteca' também é um script completo (com seu próprio onRequest/onResponse) — adicione-o como etapa para rodar a cadeia inteira, ou mantenha funções puras nele com module.exports e carregue-as com require('@libs/<key>') (veja Require de bibliotecas de scripts).
Para exemplos concretos encadeados (login para token, ida e volta AES) veja recipes.