URL path parameter와 query string 차이
API를 호출하거나 라우팅을 만들다 보면 path parameter와 query string을 자주 만난다.
둘 다 URL 안에 값을 담는 방법이지만, 의미는 다르다.
/users/42의 42는 보통 path parameter로 다룬다./users?role=admin&page=2의 role=admin&page=2는 query string으로 다룬다.
핵심 차이는 값의 역할이다.
path parameter는 주로 어떤 리소스인지 식별하는 값에 쓴다.
query string은 주로 조회 조건, 필터, 정렬, 페이지 같은 선택 조건에 쓴다.
URL의 구성
URL은 여러 부분으로 나뉜다.
아래 주소를 예로 보자.
https://example.com/users/42/posts?sort=latest&page=2#comments브라우저의 URL 객체로 보면 중요한 부분을 나눠 읽을 수 있다.
const url = new URL('https://example.com/users/42/posts?sort=latest&page=2#comments')
console.log(url.origin) // 'https://example.com'
console.log(url.pathname) // '/users/42/posts'
console.log(url.search) // '?sort=latest&page=2'
console.log(url.hash) // '#comments'pathname은 경로다.search는 ?로 시작하는 query string이다.hash는 브라우저 안에서 특정 위치나 상태를 가리킬 때 자주 쓰는 fragment다.
이 글에서는 pathname 안에 들어가는 path parameter와 search에 들어가는 query string을 비교한다.
path parameter의 역할
path parameter는 경로의 일부로 들어가는 값이다.
서버나 프레임워크는 라우트 패턴을 정해두고, 실제 URL의 일부를 변수처럼 꺼낸다.
Route pattern: /users/:userId
Actual URL: /users/42여기서 42는 userId로 해석될 수 있다.
Next.js 같은 파일 기반 라우팅에서는 아래처럼 표현할 수도 있다.
app/users/[userId]/page.tsx실제 URL은 여전히 /users/42처럼 보인다.[userId]나 :userId 같은 표기는 라우터가 값을 꺼내기 위한 약속이다.
path parameter는 보통 리소스를 식별하는 데 쓴다.
/users/42
/posts/css-position-relative와-absolute-차이
/products/100이 값이 빠지면 어떤 리소스를 요청하는지 알기 어렵다.
그래서 path parameter는 필수 값에 가깝게 다루는 경우가 많다.
query string의 역할
query string은 URL에서 ? 뒤에 붙는 값이다.
여러 값을 &로 이어 붙인다.
/posts?tag=css&page=2&sort=latest이 값들은 보통 조회 조건을 표현한다.
태그 필터, 페이지 번호, 정렬 방식, 검색어 같은 값이 여기에 잘 맞는다.
/products?category=keyboard&minPrice=50000&maxPrice=150000query string은 선택 조건을 추가하거나 바꾸기 쉽다.
같은 목록 화면에서 필터만 바꾸거나, 페이지 번호만 바꾸는 상황과 잘 맞는다.
검색 페이지도 query string과 잘 어울린다.
/search?q=javascript이런 URL은 복사해서 공유하거나 북마크하기 쉽다.
HTTP GET 요청의 조회 조건을 URL에 드러내는 방식이라고 보면 된다.GET의 기준이 헷갈린다면 HTTP GET과 POST 차이를 같이 보면 좋다.
선택 기준
값이 리소스의 정체성을 나타내면 path parameter를 쓴다.
/users/42
/posts/url-path-parameter-query-string값이 리소스 목록을 어떻게 볼지 정하는 조건이면 query string을 쓴다.
/users?role=admin
/posts?tag=javascript&page=2예를 들어 특정 사용자 상세 페이지는 path parameter가 자연스럽다.
/users/42관리자 사용자 목록은 query string이 자연스럽다.
/users?role=admin첫 번째 URL은 42번 사용자라는 리소스를 직접 가리킨다.
두 번째 URL은 사용자 목록을 보되 role=admin 조건으로 걸러서 보겠다는 뜻에 가깝다.
필수 값과 선택 조건
path parameter는 보통 필수 값이다./posts/:slug 라우트에서 slug가 없으면 특정 글을 찾을 수 없다.
/posts/쿠키와-localStorage-차이query string은 보통 없어도 기본 동작이 가능한 선택 조건이다.
/posts
/posts?tag=javascript
/posts?tag=javascript&page=2/posts는 전체 글 목록을 보여줄 수 있다.tag=javascript가 붙으면 JavaScript 태그만 보여줄 수 있다.page=2가 붙으면 두 번째 페이지를 보여줄 수 있다.
물론 모든 서비스가 이 기준을 똑같이 쓰는 것은 아니다.
하지만 초보자라면 “식별은 path, 조건은 query”로 시작하면 대부분의 API를 읽기 쉬워진다.
URLSearchParams 사용
query string은 문자열로 직접 붙일 수 있다.
const url = `/posts?tag=javascript&page=2`하지만 값이 동적으로 바뀐다면 URLSearchParams를 쓰는 편이 안전하다.
const params = new URLSearchParams()
params.set('tag', 'javascript')
params.set('page', '2')
const url = `/posts?${params.toString()}`URLSearchParams는 query string을 다루기 위한 Web API다.
값을 추가하고, 읽고, 삭제하고, 문자열로 바꿀 수 있다.
const params = new URLSearchParams('tag=javascript&page=2')
console.log(params.get('tag')) // 'javascript'
console.log(params.get('page')) // '2'현재 페이지 URL에서 query string을 읽을 때는 URL 객체와 함께 쓰면 좋다.
const url = new URL(window.location.href)
const tag = url.searchParams.get('tag')주의할 점도 있다.new URLSearchParams()는 전체 URL을 파싱하는 도구가 아니다.
전체 URL을 다룰 때는 먼저 new URL()을 만들고 searchParams를 사용한다.
const url = new URL('https://example.com/posts?tag=css')
console.log(url.searchParams.get('tag')) // 'css'여러 값 처리
같은 key를 여러 번 보낼 수도 있다.
/posts?tag=css&tag=javascript이런 경우 get()은 첫 번째 값만 가져온다.
const params = new URLSearchParams('tag=css&tag=javascript')
console.log(params.get('tag')) // 'css'모든 값을 가져오려면 getAll()을 사용한다.
console.log(params.getAll('tag')) // ['css', 'javascript']필터 UI에서 여러 태그를 선택할 수 있다면 이 방식이 자연스러울 수 있다.
다만 서버와 클라이언트가 같은 규칙을 써야 한다.
어떤 서비스는 tag=css,javascript처럼 하나의 값에 쉼표로 묶기도 하고, 어떤 서비스는 같은 key를 반복하기도 한다.
인코딩 기준
URL에는 공백, 한글, &, ?, / 같은 문자가 그대로 들어가면 의미가 깨질 수 있다.
그래서 URL에 값을 넣을 때는 인코딩을 신경 써야 한다.
const keyword = 'CSS & HTML'
const url = `/search?q=${encodeURIComponent(keyword)}`
console.log(url) // '/search?q=CSS%20%26%20HTML'encodeURIComponent()는 URL의 일부로 들어갈 값을 인코딩할 때 사용한다.
특히 사용자가 입력한 값을 query string에 직접 붙일 때 중요하다.
가능하면 문자열을 직접 조립하기보다 URLSearchParams를 쓰는 편이 실수를 줄인다.
const params = new URLSearchParams()
params.set('q', 'CSS & HTML')
console.log(`/search?${params.toString()}`)path parameter도 인코딩이 필요할 수 있다.
slug처럼 URL에 들어가는 값에는 공백이나 특수문자가 섞이지 않도록 미리 규칙을 정하는 편이 좋다.
민감한 값의 위치
path parameter와 query string은 모두 URL에 드러난다.
브라우저 주소창, 방문 기록, 서버 로그, 분석 도구, 공유된 링크에 남을 수 있다.
그래서 비밀번호, access token, 개인 식별 정보처럼 노출되면 안 되는 값은 URL에 넣지 않는 편이 좋다.
/login?password=secret이런 URL은 피해야 한다.
민감한 값을 보내야 한다면 HTTPS를 사용하고, request body나 안전한 쿠키 설계를 검토해야 한다.
브라우저 저장소와 쿠키 기준이 헷갈리면 쿠키와 localStorage 차이를 같이 보면 좋다.
흔한 실수
첫 번째 실수는 모든 값을 query string에 넣는 것이다.
/posts?slug=url-path-parameter-query-string특정 글 상세 페이지라면 아래처럼 path에 두는 편이 더 자연스럽다.
/posts/url-path-parameter-query-string두 번째 실수는 필터 값을 path에 계속 쌓는 것이다.
/posts/tag/javascript/page/2/sort/latest동작할 수는 있지만 조건이 늘어날수록 URL 구조가 딱딱해진다.
필터와 정렬, 페이지처럼 조합이 많은 값은 query string이 더 다루기 쉽다.
/posts?tag=javascript&page=2&sort=latest세 번째 실수는 URL 조립을 문자열 더하기로만 처리하는 것이다.
값에 공백이나 &가 들어오면 의도하지 않은 query string이 될 수 있다.
동적인 값은 URL, URLSearchParams, encodeURIComponent()를 사용해 조립하는 편이 안전하다.
선택 기준 정리
리소스를 식별하는 값이면 path parameter를 쓴다.
사용자 ID, 게시글 slug, 상품 ID처럼 없으면 대상이 정해지지 않는 값이 여기에 가깝다.
조회 조건을 표현하는 값이면 query string을 쓴다.
검색어, 필터, 정렬, 페이지, 탭 상태처럼 없어도 기본 화면을 보여줄 수 있는 값이 여기에 가깝다.
URL에 넣은 값은 사용자와 시스템 여러 곳에 드러날 수 있다.
민감한 값은 path에도 query에도 넣지 않는 편이 좋다.
정리하면 기준은 단순하다.
대상을 고르면 path parameter다.
보는 방식을 바꾸면 query string이다.
동적인 query string은 URLSearchParams로 다룬다.
참고 자료
