본문으로 건너뛰기

스크립트 (개발자 관점)

전송 전 / 응답 후 스크립트는 Quick Request의 맥가이버 칼입니다: 동적 서명, 암호화·복호화, 조건부 어설션, 요청 간 값 전달이 모두 여기에 있습니다. 스크립트는 JavaScript로 작성되며 내장 QuickJS 엔진에서 실행됩니다.

이 페이지는 UI에서 추가할 수 있는 것과 스크립트가 할 수 있는 것만 다룹니다. 전체 JavaScript API 시그니처는 스크립트 API 참조를 참조하세요.


하나의 요청에는 두 개의 '액션 체인'이 있습니다​

요청 편집 페이지에서 전송 전과 응답 후 체인에 여러 스텝을 추가할 수 있으며, 순서대로 실행됩니다. 각 스텝은 다음 중 하나입니다:

스텝 타입UI에서 하는 것전형적 용도
스크립트JavaScript 한 조각을 작성헤더/바디 변경, 서명, 복호화, 조건 로직
라이브러리 스크립트저장된 공용 스크립트 참조'토큰 주입', '통일된 로깅'을 여러 곳에서 재사용
추출응답에서 값을 꺼내 변수로 저장로그인 토큰을 다음 요청으로 전달
어설션응답에 대한 검증 하나 추가상태 코드 = 200, 필드 존재
대기몇 밀리초 멈춤레이트 리밋, 폴링 간격

스크립트 작성법: 두 개의 엔트리 포인트​

스크립트 엔진은 스크립트에서 잘 알려진 엔트리 함수를 찾습니다:

// 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;
}
  • 전송 전 체인에는 onRequest를, 응답 후 체인에는 onResponse를 씁니다.
  • 함수 이름은 정확히 이것이어야 합니다, 그렇지 않으면 '엔트리 포인트 없음'으로 취급되어 건너뜁니다.
  • await가 지원됩니다.

스크립트가 바꿀 수 있는 것​

요청 변경 (onRequest의 request 객체)​

하고 싶은 것방법
헤더 설정 / 덮어쓰기request.headers.set('Authorization', 'Bearer ' + tok)
쿼리 파라미터 추가/변경request.queries.set('ts', String(Date.now()))
원시 바디 읽기var text = request.body.parseText() 또는 request.body.parseJSON()
바디 전체 재작성request.body = the new string (단순 대입)

응답 읽기/변경 (onResponse의 response 객체)​

하고 싶은 것방법
상태 코드 읽기response.statusCode
응답 헤더 읽기response.headers.get('Set-Cookie')
바디 읽기response.body.parseJSON() / .parseText()
응답 바디 전체 재작성response.body = the new string — UI/결과 뷰에 재작성된 내용이 표시됩니다 (검증됨)

내장 기능 — 다시 만들 필요 없습니다​

스크립트에는 내장 도구(sdk.*)와 $ 접두 네이티브 기능이 함께 제공됩니다: 암호화, 다이제스트, 인코딩, 랜덤, JSONPath를 모두 커버합니다:

기능사용할 것
변수 읽기/쓰기 (요청 간 전달)sdk.env.get(name) / sdk.env.set(name, value)
선언적 테스트sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
JSONPath 쿼리sdk.jsonPath('$.data.id')
AES 암호화 / 복호화$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
MD5 / SHA 다이제스트 (서명)$hash.md5(...) / $hash.sha256(...) (hex 반환, 표준·상호 운용)
UUID$uuid.v4()
문자열 base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ 엔진은 QuickJS입니다: 브라우저의 crypto.subtle은 없고, crypto.getRandomValues도 이 엔진에서는 동작하지 않습니다(전달된 배열을 채우지 않음) — AES에는 $crypto, 랜덤에는 crypto.randomUUID / $uuid를 사용하세요. WebCrypto를 찾지 마세요. 전체 시그니처와 주의점: 스크립트 API 참조.


스크립트 라이브러리 require​

공용 로직은 스텝으로 추가하는 대신 CommonJS 스타일의 require()로 불러올 수도 있습니다. 키는 항상 @libs/<key>이며, 다음 순서로 해석됩니다:

  1. 스크립트 라이브러리 identifier — 정확히 일치, 리네임에도 안정적(권장)
  2. 스크립트 라이브러리 이름 — 읽기 쉽지만, 라이브러리 리네임 시 참조가 깨짐(모호한 중복 이름은 건너뜀)
  3. 내장 라이브러리 — 앱에 번들됨

내장 라이브러리​

KeyExports비고
@libs/base64encode(str) / decode(text)UTF-8 안전 Base64 (중국어·이모지 안전); decode는 공백을 무시, 무효 시퀀스는 Latin-1로 유지
@libs/hexencode(str) / decode(text)UTF-8 안전 소문자 hex; decode는 비hex 문자를 무시, 홀수 길이는 예외

둘 다 전역 별칭으로도 노출됩니다(base64.encode(...) / hex.encode(...)) — require는 명시적 임포트 스타일을 제공할 뿐입니다.

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

자신의 스크립트 라이브러리​

재사용할 함수를 스크립트 라이브러리로 저장하고(module.exports로 export, 엔트리 함수 불필요) 전/후 스크립트 어디서든 require하세요:

// 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;
}
  • 라이브러리 매니저의 require 문 복사로 안정적인 identifier 형태를 얻습니다.
  • 라이브러리는 다른 라이브러리를 require할 수 있습니다 — 의존성 클로저 전체가 자동 번들됩니다(순환은 Node 스타일로 해결, 무한 루프 없음).
  • 모듈 캐시는 실행마다 다시 만들어집니다: 라이브러리가 요청 간에 상태를 갖지 않습니다.
  • npm 패키지를 재사용하려면 먼저 단일 파일로 번들하고(예: esbuild --format=iife, 또는 Browserify/Webpack), 그 파일을 스크립트 라이브러리로 임포트한 뒤 require('@libs/<name>') 하세요. Node(Buffer/fs/crypto/process)나 DOM 의존성이 없는 순수 JS 빌드를 고르세요.
  • 없는 키는 Error: require: 未找到库 [...]를 던집니다 — 전송 전 실패는 요청을 중단하고, 응답 후 실패는 원래 응답을 유지합니다. 주석 안의 require 호출은 무시됩니다.

전체 require 의미론: 스크립트 API 참조.


여러 스크립트의 협동​

요청에 스크립트가 여러 개일 때는 같은 globalThis를 공유합니다(검증됨). 따라서:

장점: 각 스크립트가 단일 책임을 가지며 독립적으로 토글할 수 있습니다. '라이브러리 스크립트'도 완전한 스크립트입니다(자체 onRequest/onResponse 포함) — 스텝으로 추가하면 체인 전체가 실행되고, 순수 함수를 module.exports로 담아두고 require('@libs/<key>')로 불러올 수도 있습니다(스크립트 라이브러리 require 참조).

구체적인 체인 예(로그인으로 토큰 획득, AES 왕복)는 recipes를 참조하세요.