본문으로 건너뛰기
AZ Tools

URL 쿼리 빌더

base URL + 편집 가능한 key-value 쿼리 파라미터로 URL 조립 — 각 쌍 토글, 자동 percent 인코딩.

파라미터 (3)
공백:
빌드된 URL
https://api.example.com/search?q=cloudflare%20workers&page=1&sort=relevance

키·값은 encodeURIComponent로 percent 인코딩 — 모든 정상 클라이언트가 사용하는 규칙.

사용법

  1. base URL 입력. 이미 ?가 있으면 빌더가 &로 나머지 추가.
  2. key-value 행 추가. 체크박스로 삭제 없이 포함·제외.
  3. 서버 기대에 따라 공백을 %20 또는 +로 선택.

자세한 설명

펼치기

쿼리 파라미터를 한 줄씩 추가하고 수정하고 비활성화하는 깔끔한 폼이며, 결과 URL이 실시간으로 만들어집니다. 키와 값은 encodeURIComponent를 거칩니다. 공백을 %20으로 둘지 +로 접을지(form-urlencoded 변형) 고를 수 있습니다. 비활성화한 줄은 목록에 남아 있지만 출력에는 나타나지 않아, 대안을 잃지 않고 보관해 두기 좋습니다.

공백 선택은 보이는 것보다 중요합니다. %20은 URL 어디에서나 올바른 퍼센트 인코딩이지만, +가 공백을 뜻하는 곳은 application/x-www-form-urlencoded 데이터 안뿐이고 쿼리 문자열이 관례적으로 그 형식일 뿐입니다. 대부분의 서버 프레임워크는 쿼리에서 둘 다 해석하지만 경로 구간, HTTP 헤더, JSON 본문은 그렇지 않아서, 쿼리에서 복사한 +를 그런 자리에 넣으면 그대로 더하기 기호로 남습니다. 확신이 없다면 %20이 더 안전합니다.

encodeURIComponent는 !, ', (, ), *를 의도적으로 그대로 둡니다. 쿼리에서 합법이고 대부분의 서버가 받아들이지만, OAuth 서명과 일부 엄격한 파서는 퍼센트 인코딩을 기대하며, 인코딩되지 않은 형태로 계산한 서명은 검증에 실패합니다. 인코딩은 입력한 내용에 그대로 적용된다는 점도 기억해야 합니다. 이미 인코딩된 값을 붙여 넣으면 이중 인코딩이 되어 %20이 %2520이 됩니다.

같은 키가 여러 번 나와도 합치지 않고 그대로 둡니다. ?tag=a&tag=b의 의미는 URL 문법이 아니라 받는 애플리케이션이 정하기 때문입니다. PHP는 키가 []로 끝나지 않으면 마지막 값만 남기고, 레일스와 익스프레스는 배열을 만들며, Go 표준 라이브러리는 첫 값만 돌려줍니다. 중복 키가 기대대로 동작하지 않는다면 고칠 곳은 서버 쪽입니다.

자주 묻는 질문

언제 공백에 + 사용?

서버가 쿼리 문자열을 application/x-www-form-urlencoded로 다룰 때 — 옛 폼 핸들러·CGI 스크립트가 그러함. 모던 REST API는 보통 둘 다 수용. application/json POST 본문에는 %20이 안전한 기본.

중복 키 허용?

예 — 대부분 서버가 반복 키를 배열로 처리. 일부는 마지막만 보존; 확실치 않으면 API 문서 확인.

값 안에서 반드시 인코딩해야 하는 문자는?

구조로 읽힐 수 있는 것들이다. 앰퍼샌드, 등호, 공백, 그리고 무엇보다 해시다. 해시 뒤는 프래그먼트라서 서버로 전송되지 않으므로, 인코딩되지 않은 해시 하나가 값의 나머지를 요청에서 조용히 잘라낸다. 슬래시와 콜론은 질의 문자열 안에서 합법이라 그대로 두어도 되지만, 인코딩해도 해롭지 않다.

파라미터 순서가 중요한가?

서버에는 중요하지 않다. 어떤 순서로 읽어도 되기 때문이다. 하지만 그 밖의 모든 곳에서는 중요하다. 캐시와 CDN은 URL 문자열 그대로를 키로 삼으므로 같은 파라미터라도 순서가 다르면 별개의 캐시 항목이 되고, URL에 서명하거나 URL을 비교하는 것들 — 분석 도구, 서명된 링크, 중복 제거 — 은 서로 다른 문자열로 본다. 강제되지 않더라도 순서는 고정해 두는 게 좋다.

관련 도구