웹표준으로 쿼리 파라미터 다루기 (w/ URLSearchParams)

쿼리 파라미터에서 이것저것 다루는 작업이 필요할 때가 있다.

만약 직접 처리하려고 하면 복잡도, 오류 가능성, 가독성 등 여러 문제가 발생한다. 😵‍💫

let url = 'https://api.example.com/products?'

if (category) {
  url += `category=${category}`
}

if (filter) {
  // 이미 다른 파라미터가 있는지 확인
  url += (url.endsWith('?') ? '' : '&') + `filter=${filter}`
}

이때 웹표준만으로도 해당 문제를 적절하게 해결할 수 있다.

URLSearchParams

URLSearchParams는 URL의 쿼리 문자열을 쉽게 다룰 수 있게 해주는 웹 API이다.

해당 API를 통해 쿼리 파라미터를 객체처럼 다룰 수 있다.

const params = new URLSearchParams()

if (category) {
  params.append('category', category)
}

if (filter) {
  params.append('filter', filter)
}

const url = `https://api.example.com/products?${params}`

문자열 처리나 불필요한 분기 처리를 할 필요가 없어졌다.

주요 메서드

이외에도 URLSearchParams는 여러 편리한 메서드를 제공해준다.

자주 사용할 메서드 문법들을 정리해보자.

생성하기

// 빈 객체 생성
const params = new URLSearchParams()

// 문자열로부터 생성
const params = new URLSearchParams('category=shirts&color=blue') // ?category=shirts&color=blue로 해도 동일하다.

// 객체로부터 생성
const params = new URLSearchParams({
  category: 'shirts',
  color: 'blue',
})

파라미터 추가 및 설정

// 파라미터 추가 (동일 키에 여러 값 가능하다.)
params.append('size', 'M')
params.append('size', 'L') // size=M&size=L

// 파라미터 설정 (기존 값 덮어쓴다.)
params.set('size', 'XL') // size=XL

파라미터 가져오기

// 첫 번째 값 가져오기
const size = params.get('size') // 'XL'

// 모든 값 배열로 가져오기
const allSizes = params.getAll('size') // ['XL']

// 파라미터 존재 여부 확인
const hasDiscount = params.has('discount') // false

파라미터 삭제하기

// 특정 키의 모든 값 삭제
params.delete('size')

반복하기

이터러블하게 사용 가능하다.

// 모든 파라미터 순회
for (const [key, value] of params) {
  console.log(`${key}: ${value}`)
}

// 키 목록 가져오기
for (const key of params.keys()) {
  console.log(key)
}

// 값 목록 가져오기
for (const value of params.values()) {
  console.log(value)
}

문자열 변환

// 문자열로 변환
const queryString = params.toString() // 'category=shirts&color=blue'

URLSearchParams

주요 메서드

참고 문서