본문으로 건너뛰기

syn.$r (request) 사용법

$request 모듈(별칭 syn.$r)은 queryString 조회/생성, url 변환, http 요청(fetch/XHR), Cookie 조작 기능을 제공합니다.

이 모듈의 예제는 두 개의 페이지로 나뉘어 있으며, 이 문서는 두 예제를 함께 다룹니다.

  • request.html/request.js — $w.initializeScript({ ... }) 형태로 이벤트 핸들러를 등록하는 레거시 방식 예제입니다. 페이지 전체를 하나의 플랫 객체로 등록하며, hook/event/method 같은 구획 없이 {요소ID}_{이벤트명} 형태의 함수명을 그대로 키로 사용합니다. query/url/toQueryString/toUrlObject/Cookie 조작 등 기본 기능만 다룹니다.
  • requests.html/requests.js — let $requests = { extends, hook, method, event } 형태의 객체로 이벤트 핸들러를 등록하는 현행 방식 예제입니다. hook.pageLoad()에서 초기값을 세팅하고, event 구획 아래에 {요소ID}_{이벤트명} 형태의 함수를 선언합니다. resolveUrl, addQueryParam/removeQueryParam/setQueryParam, isCorsEnabled, httpFetch/httpRequest/httpSubmit/httpDataSubmit를 포함한 $request의 전체 공개 API를 다룹니다.

개요​

  • 모듈: $request (별칭 syn.$r)
  • 파일: request.html/request.js (레거시 등록 방식), requests.html/requests.js (현행 등록 방식)
  • 범위: queryString 조회/생성, url 변환, queryString 파라미터 추가/제거/설정, CORS 확인, httpFetch/httpRequest/httpSubmit/httpDataSubmit를 통한 http 요청, Cookie 조작까지 $request의 전체 공개 API

사용법 - 레거시 방식 (request.js)​

request.js는 다음과 같이 요소ID와 이벤트명을 조합한 키로 핸들러를 등록합니다.

$w.initializeScript({
    btnQuery_click() {
        syn.$r.params['p1'] = 'aaa';
        syn.$r.params['p2'] = 'bbb';
        syn.$r.params['p3'] = 'ccc';
        syn.$l.get('txtQuery').value = syn.$r.query('p2');
    },
    btnUrl_click() {
        syn.$l.get('txtUrl').value = syn.$r.url();
    },
    btnSetCookie_click() {
        syn.$r.setCookie('txtSetCookie', 'hello');
    },
})

syn.$r.params는 $request 모듈이 내부적으로 들고 있는 queryString 저장소이며, query()와 url()은 이 값을 읽고 씁니다. 화면에서 각 입력란과 버튼을 눌러 값을 채운 뒤 결과를 확인할 수 있습니다.

화면 구성 (request.html)​

항목설명
$request.querysyn.$r.params에 값을 채운 뒤 query('p2')로 조회합니다.
$request.urlsyn.$r.params의 값으로 queryString이 포함된 url을 생성합니다.
$request.toQueryString간단한 json 값을 queryString 문자열로 변환합니다(isQuestion=true로 ? 접두 포함).
$request.toUrlObject현재 페이지 url의 queryString을 객체로 변환합니다.
$request.setCookie'txtSetCookie'라는 이름으로 쿠키 값을 설정합니다.
$request.getCookie설정된 쿠키 값을 조회합니다.
$request.deleteCookie설정된 쿠키 값을 삭제합니다.

사용법 - 현행 방식 (requests.js)​

'use strict';
let $requests = {
    extends: ['parsehtml'],

    hook: {
        pageLoad() {
            syn.$l.get('txt_params').value = JSON.stringify(syn.$r.params);
            syn.$l.get('txt_path').value = syn.$r.path;
        }
    },

    event: {
        btn_query_click() {
            syn.$l.get('txt_query').value = syn.$r.query('param1');
        },
        async btn_httpFetch_click() {
            const result = await syn.$r.httpFetch('sample.json').send();
            syn.$l.get('txt_httpFetch').value = JSON.stringify(result);
        },
    }
};

페이지 로드 시 hook.pageLoad()가 syn.$r.params, syn.$r.path 값을 화면에 출력하고, 각 카드의 입력란/버튼을 조작하면 event 구획의 핸들러가 해당 $request 메서드를 호출합니다.

화면 구성 (requests.html)​

속성​

항목설명
syn.$r.params현재까지 조회된 queryString 값을 담고 있는 객체입니다.
syn.$r.path현재 페이지의 location.pathname 값입니다.

메서드​

항목설명
query(param, url)url(생략 시 현재 페이지)에서 queryString 파라미터 값을 조회합니다.
url()syn.$r.params 값으로 현재 경로에 대한 queryString url을 생성합니다.
toQueryString(jsonObject, isQuestion)json 객체를 queryString 문자열로 변환합니다.
toUrlObject(url)url(생략 시 현재 페이지)의 queryString을 json 객체로 변환합니다.
resolveUrl(relativePath, baseUrl)상대 경로를 절대 url로 변환합니다.
addQueryParam(param, value, urlStr)url에 queryString 파라미터를 추가합니다.
removeQueryParam(paramName, urlStr)url에서 queryString 파라미터를 제거합니다.
setQueryParam(param, value, urlStr)url의 queryString 파라미터 값을 설정(대체)합니다.
isCorsEnabled(url)대상 url에 CORS로 접근 가능한지 HEAD 요청으로 확인합니다.
httpFetch(url)fetch API 기반 http 요청 객체를 반환합니다(.send(raw, options) 호출).
httpRequest(method, url, data, callback, options)XMLHttpRequest 기반으로 http 요청을 수행합니다.
httpSubmit(url, formID, method)지정한 form을 method, url 값으로 설정 후 submit()합니다.
httpDataSubmit(formData, url, callback, options)FormData 객체를 XMLHttpRequest로 POST 전송합니다.
getCookie(id)현재 웹 사이트의 쿠키 데이터를 조회합니다.
setCookie(id, val, expires, path, domain, secure)현재 웹 사이트에 쿠키 데이터를 설정합니다.
deleteCookie(id, path, domain)현재 웹 사이트의 쿠키 데이터를 삭제합니다.

주의 사항​

과거 버전에서는 requests.html 상단 "속성" 카드에 syn.$r.version 항목이 있었으나, $request 모듈에는 version 속성이 존재하지 않고(참조 코드도 $request가 아닌 $keyboard(syn.$k)의 값을 잘못 참조하고 있었음) 정리 과정에서 제거하고 실제로 존재하는 syn.$r.path 속성으로 대체했습니다.

관련 모듈​

API 상세 목록은 아래 API 참조 섹션를 참고하세요.

API 참조​

모듈 정보​

  • 이름: $request
  • 별칭: syn.$r
  • 위치: 2.Modules/wwwroot/wwwroot/js/syn.js (약 5556~6054번째 줄)
  • 설명: http 요청, URL/queryString 조작, Cookie 조작 기능을 제공하는 모듈입니다.

속성​

속성타입설명
paramsobject조회된 queryString 값을 담는 객체입니다. 초기값은 {}이며 query() 호출 시 채워집니다.
pathstring현재 페이지의 location.pathname 값입니다(Node 환경에서는 빈 문자열).
createBlobUrlfunctionURL.createObjectURL(또는 webkitURL.createObjectURL)에 바인딩된 함수입니다.
revokeBlobUrlfunctionURL.revokeObjectURL(또는 webkitURL.revokeObjectURL)에 바인딩된 함수입니다.

메서드 요약​

메서드반환설명
query(param, url)`string \undefined`
url()stringparams 값으로 현재 경로의 queryString url 생성
toQueryString(jsonObject, isQuestion)stringjson 객체를 queryString 문자열로 변환
toUrlObject(url)objecturl의 queryString을 json 객체로 변환
resolveUrl(relativePath, baseUrl)string상대 경로를 절대 url로 변환
addQueryParam(param, value, urlStr)stringqueryString 파라미터 추가
removeQueryParam(paramName, urlStr)stringqueryString 파라미터 제거
setQueryParam(param, value, urlStr)stringqueryString 파라미터 설정(대체)
isCorsEnabled(url)Promise<boolean>대상 url의 CORS 접근 가능 여부 확인
httpFetch(url)Proxy (.send())fetch 기반 http 요청
httpRequest(method, url, data, callback, options)`Promise \void`
httpSubmit(url, formID, method)`boolean \void`
httpDataSubmit(formData, url, callback, options)`Promise \void`
getCookie(id)`string \undefined`
setCookie(id, val, expires, path, domain, secure)$request쿠키 값 설정(체이닝 가능)
deleteCookie(id, path, domain)$request쿠키 값 삭제(체이닝 가능)

메서드 상세​

query(param, url)​

url(생략 시 location.href)의 queryString을 파싱하여 syn.$r.params에 채운 뒤, param 키에 해당하는 값을 반환합니다. 값에 %XX 형식의 인코딩 문자가 포함되어 있으면 자동으로 decodeURIComponent로 복원합니다.

syn.$r.query('page');                                    // 현재 페이지 url 기준 조회
syn.$r.query('page', '/list.html?page=2&size=10');        // 지정 url 기준 조회

url()​

syn.$r.path와 syn.$r.params의 문자열 값들을 조합해 queryString이 포함된 url을 생성합니다. syn.Config.IsClientCaching이 false이면 캐시 무효화를 위한 noCache 파라미터가 자동으로 추가됩니다.

syn.$r.params.page = '2';
const url = syn.$r.url(); // 예: /list.html?page=2

toQueryString(jsonObject, isQuestion)​

json 객체를 key=value&key=value 형태의 queryString 문자열로 변환합니다. isQuestion이 true이면 문자열 맨 앞에 ?를 붙입니다.

syn.$r.toQueryString({ page: '1', size: '2kg' });        // page=1&size=2kg
syn.$r.toQueryString({ page: '1' }, true);                // ?page=1

toUrlObject(url)​

url(생략 시 location.href)의 queryString 부분을 파싱하여 json 객체로 변환합니다.

syn.$r.toUrlObject('/list.html?page=1&size=10');
// { page: '1', size: '10' }

resolveUrl(relativePath, baseUrl)​

URL 생성자를 이용해 상대 경로(relativePath)를 기준 url(baseUrl, 생략 시 location.href)에 대한 절대 url로 변환합니다.

syn.$r.resolveUrl('/api/v1/users', 'https://example.com');
// https://example.com/api/v1/users
syn.$r.resolveUrl('../v1/users/', 'https://example.com/api/v2');
// https://example.com/api/v1/users

addQueryParam(param, value, urlStr)​

url(urlStr, 생략 시 location.href)에 queryString 파라미터를 추가합니다. param이 객체이면 {key: value, ...} 형태로 여러 개를 한 번에 추가할 수 있고, 문자열이면 value와 함께 단일 파라미터를 추가합니다. 잘못된 형식이면 경고 로그를 남기고 원본 url을 반환합니다.

syn.$r.addQueryParam('page', '2', 'https://example.com/list?size=10');
// https://example.com/list?size=10&page=2

removeQueryParam(paramName, urlStr)​

url에서 지정한 queryString 파라미터를 제거합니다. paramName은 문자열 또는 문자열 배열입니다.

syn.$r.removeQueryParam('size', 'https://example.com/list?page=2&size=10');
// https://example.com/list?page=2

setQueryParam(param, value, urlStr)​

url의 queryString 파라미터 값을 설정(이미 있으면 대체)합니다. param이 객체이면 여러 개를 한 번에 설정할 수 있습니다.

syn.$r.setQueryParam('size', '20', 'https://example.com/list?page=2&size=10');
// https://example.com/list?page=2&size=20

isCorsEnabled(url)​

fetch(url, { method: 'HEAD' }) 요청으로 대상 url에 CORS로 접근 가능한지 확인하는 비동기 메서드입니다. 응답 상태 코드가 200~299이면 true를 반환합니다.

const enabled = await syn.$r.isCorsEnabled('https://example.com/api/data');

httpFetch(url)​

fetch API 기반의 요청 객체(Proxy)를 반환합니다. 반환된 객체는 send 액션만 지원하며, send(raw, options) 호출 시 실제 요청이 수행됩니다. raw가 문자열이 아니고 null/undefined도 아니면 POST 방식 본문으로 전송하고, 그 외에는 GET 방식으로 요청합니다. 응답의 Content-Type에 따라 json/text/blob 중 알맞은 형태로 자동 파싱하여 반환합니다.

const result = await syn.$r.httpFetch('/api/users').send();
const created = await syn.$r.httpFetch('/api/users').send({ name: 'hong' }, { method: 'POST' });

httpRequest(method, url, data, callback, options)​

XMLHttpRequest 기반으로 http 요청을 수행합니다. data.body가 있으면 GET은 queryString으로, 그 외 메서드는 FormData로 전송합니다. callback을 생략하면 Promise를 반환합니다.

const result = await syn.$r.httpRequest('GET', '/api/users');
syn.$r.httpRequest('POST', '/api/users', { body: { name: 'hong' } }, (result) => {
    console.log(result.status, result.response);
});

httpSubmit(url, formID, method)​

document.forms에서 formID(생략 시 첫 번째 form)를 찾아 action/method를 설정한 뒤 submit()을 호출합니다. form이 없으면 false를 반환합니다.

syn.$r.httpSubmit('/upload', 'form1', 'POST');

httpDataSubmit(formData, url, callback, options)​

FormData 객체를 XMLHttpRequest로 POST 전송합니다. callback을 생략하면 Promise를 반환합니다.

const formData = new FormData();
formData.append('file', fileInput.files[0]);
const result = await syn.$r.httpDataSubmit(formData, '/upload');

getCookie(id)​

document.cookie에서 id에 해당하는 쿠키 값을 조회하여 decodeURIComponent로 복원해 반환합니다. 없으면 undefined를 반환합니다.

const value = syn.$r.getCookie('Cookie');

setCookie(id, val, expires, path, domain, secure)​

쿠키 값을 설정합니다. expires를 생략하면 24시간 뒤 만료되며, path를 생략하면 /가 사용됩니다. $request 인스턴스($request 자기 자신)를 반환하여 체이닝이 가능합니다.

syn.$r.setCookie('Cookie', 'hello world');
syn.$r.setCookie('Cookie', 'hello world', new Date(Date.now() + 1000 * 60 * 60), '/', undefined, true);

deleteCookie(id, path, domain)​

지정한 쿠키가 존재하면 만료 시각을 과거로 설정해 삭제합니다. $request 인스턴스를 반환합니다.

syn.$r.deleteCookie('Cookie');