Node.js url 모듈 — URL 파싱과 처리

웹 서버를 만들면 요청 URL을 파싱해서 경로나 쿼리 문자열을 꺼내야 하는 일이 아주 흔해요. Node.js의 node:url 모듈은 URL을 파싱하고 조립하는 유틸리티를 제공해요. URL 문자열을 파싱하면 각 구성 요소를 담은 프로퍼티를 가진 URL 객체가 돌아와요.

출처: URL | Node.js Documentation

node:url 모듈은 이렇게 불러와요.

import url from 'node:url';
const url = require('node:url');

URL 문자열과 URL 객체

URL 문자열은 여러 의미 있는 구성 요소를 담은 구조화된 문자열이에요. 파싱하면 각 구성 요소에 대한 프로퍼티를 가진 URL 객체를 돌려줘요.

node:url 모듈은 URL을 다루는 두 가지 API를 제공해요. 하나는 Node.js 전용의 레거시 API이고, 다른 하나는 웹 브라우저에서 쓰는 것과 같은 WHATWG URL 표준을 구현한 더 새로운 API예요.

예를 들어 'https://user:[email protected]:8080/p/a/t/h?query=string#hash'라는 URL이 있을 때, 레거시 url.parse()가 돌려주는 객체와 WHATWG URL 객체는 구성 요소마다 그 표현이 달라요.

WHATWG URL 클래스

new URL(input[, base])로 URL 객체를 만들 수 있어요. url.protocol, url.hostname, url.port, url.pathname, url.search, url.hash 같은 프로퍼티로 각 부분을 읽을 수 있어요.

const myURL = new URL('https://user:[email protected]:8080/p/a/t/h?query=string#hash');

myURL.protocol;   // 'https:'
myURL.hostname;   // 'sub.example.com'
myURL.port;       // '8080'
myURL.pathname;   // '/p/a/t/h'
myURL.search;     // '?query=string'
myURL.hash;       // '#hash'

url.searchParams

url.searchParams는 URLSearchParams 객체로 쿼리 문자열을 편리하게 다룰 수 있게 해 줘요.

const params = new URLSearchParams('?a=1&b=2');
params.get('a');          // '1'
params.getAll('b');       // ['2']
params.append('c', '3');  // 추가
params.toString();        // 'a=1&b=2&c=3'

URLSearchParams는 get·getAll·has·set·append·delete·sort 같은 메서드와 size 프로퍼티를 제공해서 쿼리 파라미터를 읽고 조작하는 데 유용해요.

URL.canParse / URL.parse

URL.canParse(input[, base])는 URL 문자열을 파싱할 수 있는지 불리언을 돌려주고, URL.parse(input[, base])는 성공하면 URL 객체, 실패하면 null을 돌려줘요.

레거시 API

레거시 url.parse()는 URL 문자열을 urlObject로 파싱해요. auth, hash, host, hostname, href, path, pathname, port, protocol, query, search, slashes 같은 프로퍼티를 가져요.

import url from 'node:url';
const parsed = url.parse('/p/a/t/h?query=string#hash');
parsed.pathname;  // '/p/a/t/h'
parsed.query;     // 'query=string'

파일 URL 변환

url.fileURLToPath(url)은 file:// URL을 파일 경로로, url.pathToFileURL(path)은 파일 경로를 file:// URL로 바꿔 줘요. ESM에서 import.meta.url 같은 걸 다룰 때 자주 쓰여요.

정리하면, url 모듈은 브라우저와 같은 WHATWG URL/URLSearchParams API와 Node.js 전용 레거시 API를 함께 제공해서, URL 파싱·쿼리 처리·파일 URL 변환을 모두 해결해 줘요.

Node.js url 모듈 — URL 파싱과 처리