Pular para o conteúdo principal

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 etapaO que você faz na UIUso típico
ScriptEscreve um trecho de JavaScriptMudar headers/body, assinatura, descriptografia, lógica condicional
Script de bibliotecaReferencia um script compartilhado salvoReutilizar 'injetar token', 'logging unificado' em vários lugares
ExtraçãoPega um valor da resposta e armazena como variávelPassar o token de login para a próxima requisição
AsserçãoAdiciona uma validação contra a respostaCódigo de status = 200, um campo existe
EsperaPausa por alguns milissegundosRate 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 onRequest na cadeia de pré-envio, onResponse na 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ê querComo
Definir / sobrescrever um headerrequest.headers.set('Authorization', 'Bearer ' + tok)
Adicionar / mudar um query paramrequest.queries.set('ts', String(Date.now()))
Ler o corpo brutovar text = request.body.parseText() ou request.body.parseJSON()
Reescrever o corpo inteirorequest.body = the new string (atribuição simples)

Lendo / mudando a resposta (o objeto response no onResponse)​

Você querComo
Ler o código de statusresponse.statusCode
Ler um header da respostaresponse.headers.get('Set-Cookie')
Ler o corporesponse.body.parseJSON() / .parseText()
Reescrever o corpo inteiro da respostaresponse.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:

CapacidadeO que usar
Ler / escrever variáveis (passagem entre requisições)sdk.env.get(name) / sdk.env.set(name, value)
Testes declarativossdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Consultas JSONPathsdk.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 stringsdk.utils.base64Encode(str) / base64Decode(str)

⚠️ O motor é QuickJS: não existe crypto.subtle de browser, e crypto.getRandomValues não funciona neste motor (não preenche o array passado) — use $crypto para AES, e crypto.randomUUID / $uuid para 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:

  1. Identificador da biblioteca de scripts — correspondência exata, estável entre renomeações (recomendado)
  2. Nome da biblioteca de scripts — legível, mas renomear a biblioteca quebra a referência (nomes duplicados ambíguos são pulados)
  3. Bibliotecas integradas — empacotadas com o app

Bibliotecas integradas​

ChaveExportsNotas
@libs/base64encode(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/hexencode(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 require de 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 depois require('@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. Chamadas require dentro 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.