본문으로 건너뛰기

클래식 시나리오 레시피

concepts와 스크립트를 실전 워크플로로 조합합니다. 각 시나리오는 목표 → 흐름 → UI에 바로 붙여넣을 수 있는 스크립트 → 기대 결과를 제공합니다. 모든 스크립트 로직은 실제 앱에서 엔드투엔드로 검증되었습니다.

예제는 로컬 테스트 서버(/oauth2/token, /protected, /echo, /json 등)를 사용합니다. 자신의 API를 대상으로 할 때는 경로와 Pre-URL을 교체하세요.


시나리오 1: 로그인으로 토큰 획득, 그룹 전체에 자동 부착​

목표: 로그인 API를 호출하고 토큰을 저장한 뒤, 이후의 모든 요청에 자동으로 부착합니다 — 수동 복사가 필요 없습니다.

요청 A — 로그인 (응답 후 스크립트가 토큰을 저장)​

POST /oauth2/token, form 바디: grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret

응답 후 체인에 스크립트 스텝을 하나 추가합니다:

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
if (j && j.access_token) {
sdk.env.set('authToken', j.access_token); // store on the runtime blackboard
sdk.env.set('tokenType', j.token_type || 'Bearer');
}
return response;
}

요청 B — 토큰 부착 (같은 스크립트를 모든 인가 API에 복사 가능)​

GET /protected, 전송 전 체인에 스크립트 스텝을 하나 추가합니다:

async function onRequest(context, url, request) {
var tok = sdk.env.get('authToken'); // take from the blackboard
var ty = sdk.env.get('tokenType') || 'Bearer';
if (tok) { request.headers.set('Authorization', ty + ' ' + tok); }
return request;
}

기대 결과​

동작결과
먼저 A 전송 (로그인)200, 응답에 access_token 포함, 토큰 저장됨
이어서 B 전송 (부착)200, 응답 {authorized:true, ...}
스크립트를 끄고 B 재전송401 (전송 전 체인이 실행되지 않음 → 토큰 미주입 — 토큰을 부착하는 것은 스크립트라는 증명)

핵심: A와 B는 같은 환경에 바인딩된 같은 그룹에 있어야 합니다(런타임 변수는 환경 단위 스코프). 경로 조각은 환경 Pre-URL로 완성됩니다.


시나리오 2: 요청 본문 AES 암호화, 응답 복호화 (멀티 스크립트 체인)​

목표: 전송 전에 바디를 AES 암호화하고(와이어에는 암호문만), 응답이 도착하면 복호화합니다. 여러 스크립트의 체이닝과 스크립트 간 데이터 공유도 시연합니다.

왜 여러 스크립트로 나눌 수 있을까요? 같은 체인의 스크립트는 globalThis를 공유합니다: 스크립트 ①이 키/평문을 숨겨두면, 스크립트 ②③이 꺼내 씁니다. 각 스크립트는 단일 책임을 유지하며 독립적으로 토글할 수 있습니다.

전송 전 체인​

스크립트 ① (컨텍스트와 키 준비):

async function onRequest(context, url, request) {
globalThis.__traceId = $uuid.v4();
globalThis.__aesKey = '0123456789abcdef'; // 16 bytes → AES-128
globalThis.__aesIv = 'abcdef0123456789';
globalThis.__plain = request.body.parseText();
request.headers.set('X-Trace-Id', globalThis.__traceId);
return request;
}

스크립트 ② (바디 암호화):

async function onRequest(context, url, request) {
var cipher = $crypto.encryptAES(globalThis.__plain, globalThis.__aesKey, globalThis.__aesIv);
request.body = cipher; // only ciphertext on the wire
request.headers.set('X-Encrypt', 'AES-128-CBC');
return request;
}

(선택) 스크립트 ③은 시나리오 1의 토큰 부착 로직을 추가합니다.

응답 후 체인 (복호화 + 응답 재작성)​

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
var cipher = j && j.body && j.body.utf8; // /echo echoes the request body in body.utf8
var recovered = cipher ? $crypto.decryptAES(cipher, globalThis.__aesKey, globalThis.__aesIv) : '';
var obj = null; try { obj = JSON.parse(recovered); } catch (e) {}
response.body = JSON.stringify({
traceId: globalThis.__traceId, decrypted: recovered,
roundtripOk: recovered === globalThis.__plain, jsonValid: !!obj,
});
return response;
}

요청 바디 (암호화 전): {"order":123,"note":"secret-payload","amount":99.5}

기대 결과​

전송하면 다음을 얻습니다:

{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
  • roundtripOk:true: 복호화 결과가 원래 평문과 바이트 단위로 일치합니다
  • 재작성된 응답 바디가 결과에 표시됩니다(응답 후 재작성이 실제로 적용되었음의 증명)

⚠️ $crypto 인자는 위치 지정 문자열입니다. 실패 시 Error:로 시작하는 문자열만 돌려주고 예외를 던지거나 중단하지 않습니다(검증됨: 잘못된 암호문 → Invalid ciphertext, 틀린 키/iv → CryptoKit error). 중국어/비ASCII 평문도 정상적으로 암호화·복호화됩니다('비ASCII는 중단된다'는 예전 주장은 반증되었습니다). 복호화 결과를 HTTP 헤더에 쓰려면 값이 ASCII인지 확인하세요(헤더 값은 비ASCII를 거부하며, 그렇지 않으면 TypeError가 던져집니다). UTF-8 내용은 body나 쿼리 파라미터에 넣으세요.


시나리오 3: 추출 · 어설션 · 동적 변수 · 서명​

경량 자동화 모음입니다 — 대부분은 JS 없이 선언적 추출 / 어설션 스텝으로 처리됩니다.

3.1 응답 필드를 다음 요청으로 전달 (추출)​

  • 요청 A의 응답 후 체인에 추출 스텝을 추가합니다: 변수 author, 소스 response body JSON, 표현식 $.slideshow.author.
  • 요청 B의 전송 전 체인에 스크립트 스텝을 추가합니다: var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;

검증됨: 요청 B의 /echo는 요청 A의 응답에 있던 author와 일치하는 X-Extracted 헤더를 돌려줍니다.

3.2 어설션​

응답 후 체인에 어설션 스텝을 추가합니다: 상태 코드 = 200, $.slideshow.title exists. 결과는 하나씩 나열됩니다(통과/실패, 기대값 vs 실제값).

3.3 동적 변수​

params / headers / URL에 바로 씁니다:

GET /echo?ts={{$timestamp}}&r={{$randomInt}}&u={{$uuid}}

검증됨: 전송할 때마다 ts는 현재 타임스탬프, r은 다른 랜덤 정수, u는 유효한 UUID로 돌아옵니다. 전체 목록: concepts, 동적 변수.

3.4 서명 (MD5, 표준·상호 운용)​

많은 오픈 API가 MD5(param concatenation + secret)로 서명합니다. 검증된 표준 $hash.md5를 사용하세요:

async function onRequest(context, url, request) {
var appId = sdk.env.get('appId');
var secret = sdk.env.get('appSecret'); // keep secrets in environment variables
var ts = String(Math.floor(Date.now() / 1000));
var sign = $hash.md5(appId + ts + secret); // concatenation order per your backend's convention
request.queries.set('appId', appId);
request.queries.set('ts', ts);
request.queries.set('sign', sign);
return request;
}

검증됨: $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, 백엔드와 일치합니다.

✅ 네이티브 $hmac($hmac.sha256(message, key) 등)은 표준 RFC HMAC과 벡터 단위로 검증되어 외부 서명에 사용할 수 있습니다(인자 순서 주의: 데이터가 먼저, 키가 나중). $hash 계열도 표준입니다. $jwt만 객체 페이로드를 [object Object]로 퇴화시키므로(먼저 JSON.stringify로 문자열화하거나 서버에서 서명하세요).


시나리오 4: 라이브러리 스크립트와 require()로 공통 로직 재사용​

목표: '토큰 주입', '통일된 서명', '로깅'을 재사용 가능한 단위로 추출합니다 — 여러 곳에서 참조하고, 한 곳에서 관리합니다.

재사용 방법은 두 가지입니다:

  • 라이브러리 스크립트 스텝: 자체 onRequest/onResponse를 가진 완전한 스크립트입니다 — 스텝으로 추가하면 순서대로 실행되며, 다른 스텝과 globalThis를 공유합니다.
  • require(): 순수 함수를 module.exports로 스크립트 라이브러리에 저장하면, 어떤 스크립트에서든 불러올 수 있습니다 — 서명 헬퍼, 코덱 등 공용 유틸리티에 적합합니다:
// script library "sign-lib" (no entry function needed)
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('appSecret')));
return request;
}

라이브러리 매니저의 require 문 복사로 안정적인 identifier 형태를 얻으세요. 내장 라이브러리(@libs/base64, @libs/hex)는 설정 없이 어디서든 사용할 수 있습니다. 전체 메커니즘: 스크립트, 스크립트 라이브러리 require.


시나리오 치트시트​

하고 싶은 것어떤 스텝
로그인 후 모든 API에 토큰 자동 부착응답 후 스크립트가 저장 + 전송 전 스크립트가 읽어 헤더에 주입
요청 바디 암호화 / 응답 복호화전송 전 $crypto.encryptAES + 응답 후 decryptAES
응답 필드를 다음 요청으로 전달추출 스텝 + 변수를 읽는 스크립트
상태 코드 / 필드 검증어설션 스텝
전송마다 랜덤 값 / 타임스탬프 생성{{$uuid}} 같은 동적 변수
오픈 API 서명$hash.md5(...) (표준)
같은 로직을 여러 곳에서 재사용라이브러리 스크립트, 또는 스크립트 라이브러리를 require('@libs/<key>')