URL 인코딩과 쿼리 스트링: 실용 가이드

URL은 경로와 쿼리에서 제한된 문자 집합만 허용합니다. 그 외의 모든 문자는 퍼센트 인코딩되어야 합니다(예: 공백 → %20, & → %26). 이를 잘못 처리하면 404 오류, 깨진 애널리틱스 태그, 그리고 미묘한 API 버그로 이어집니다.

어떤 문자가 인코딩되나요?

• 공백, &, =, #, 또는 비ASCII 텍스트(이모지, 악센트)를 포함하는 쿼리 값은 반드시 인코딩해야 합니다.
• 슬래시나 특수 문자가 포함된 경로 세그먼트도 인코딩이 필요합니다—그렇지 않으면 라우터가 세그먼트 경계를 잘못 해석합니다.

브라우저는 주소 표시줄에 "보기 좋은" URL을 표시하면서, 실제 전송 시에는 인코딩된 형태를 사용합니다. 하지만 API를 사용할 때는 문자열을 직접 조합할 경우 명시적으로 인코딩해야 합니다.

encodeURIComponent vs encodeURI

JavaScript에서:

• encodeURIComponent — 쿼리 파라미터 값(그리고 보통 키)에 사용합니다. URL을 깨뜨릴 수 있는 거의 모든 문자를 인코딩합니다.
• encodeURI — ?나 # 같은 구분자를 유지해야 할 때 전체 URL에만 사용합니다. 일반적인 API 작업에서는 드물게 쓰입니다.

const q = "hello world & friends";
const params = new URLSearchParams({ q });
console.log(params.toString()); // q=hello+world+%26+friends

URLSearchParams는 표준 application/x-www-form-urlencoded 방식의 쿼리 인코딩을 자동으로 처리하며, 수동 문자열 연결보다 권장됩니다.

여러 파라미터로 URL 구성하기

UTM 태그, 필터, 또는 API 키를 추가할 때 실수가 쌓이기 쉽습니다: 중복된 ?, 인코딩되지 않은 &, 또는 모호한 순서 문제 등이 있습니다. 작은 헬퍼 함수나 시각적 빌더를 사용하면 최종 문자열을 유효하게 유지할 수 있습니다.

URL Encode / Decode 도구로 문자열이 어떻게 변환되는지 확인하고, URL & Query String Builder로 UTF-8 안전 인코딩을 적용한 완전한 링크를 조합해 보세요.

cURL과 fetch

브라우저 개발자 도구에서 요청을 복사할 때, 이미 인코딩된 쿼리 스트링에 주의하세요. 코드에 그대로 붙여넣으면 값이 이중 인코딩될 수 있습니다. cURL to fetch() 변환 도구를 사용하면 작동하는 cURL을 JavaScript로 변환하면서 URL을 별도로 검증할 수 있습니다.

링크가 "Chrome에서는 작동"하지만 스크립트에서 실패한다면, 원시 쿼리 스트링을 바이트 단위로 비교해 보세요.

간단한 체크리스트

• ?a=...&b=...에 연결하기 전에 값을 인코딩하세요
• 수동 문자열 조합 대신 URL + URLSearchParams 사용을 권장합니다
• 국제화 도메인 이름(IDN)의 경우, 브라우저가 호스트명의 퓨니코드 처리를 담당하므로 경로와 쿼리 인코딩에 집중하세요