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.query`	`syn.$r.params`에 값을 채운 뒤 `query('p2')`로 조회합니다.
`$request.url`	`syn.$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 참조

모듈 정보

이름: $request
별칭: syn.$r
설명: http 요청, URL/queryString 조작, Cookie 조작 기능을 제공하는 모듈입니다.

속성

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

메서드 요약

메서드	반환	설명
`query(param, url)`	`string \	undefined`
`url()`	`string`	`params` 값으로 현재 경로의 queryString url 생성
`toQueryString(jsonObject, isQuestion)`	`string`	json 객체를 queryString 문자열로 변환
`toUrlObject(url)`	`object`	url의 queryString을 json 객체로 변환
`resolveUrl(relativePath, baseUrl)`	`string`	상대 경로를 절대 url로 변환
`addQueryParam(param, value, urlStr)`	`string`	queryString 파라미터 추가
`removeQueryParam(paramName, urlStr)`	`string`	queryString 파라미터 제거
`setQueryParam(param, value, urlStr)`	`string`	queryString 파라미터 설정(대체)
`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 중 알맞은 형태로 자동 파싱하여 반환합니다. 기본 fetch 옵션은 CORS 모드, 동일 출처 자격 증명, JSON 요청/응답 헤더, 리다이렉트 추적과 no-referrer-when-downgrade Referrer Policy를 사용합니다. 호출 시 전달한 options로 기본값을 재정의할 수 있습니다.

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');

개요​

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

화면 구성 (request.html)​

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

화면 구성 (requests.html)​

속성​

메서드​

주의 사항​

관련 모듈​

API 참조​

모듈 정보​

속성​

메서드 요약​

메서드 상세​

query(param, url)​

url()​

toQueryString(jsonObject, isQuestion)​

toUrlObject(url)​

resolveUrl(relativePath, baseUrl)​

addQueryParam(param, value, urlStr)​

removeQueryParam(paramName, urlStr)​

setQueryParam(param, value, urlStr)​

isCorsEnabled(url)​

httpFetch(url)​

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

httpSubmit(url, formID, method)​

httpDataSubmit(formData, url, callback, options)​

getCookie(id)​

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

deleteCookie(id, path, domain)​

개요