JSON

쿼리 문자열

JSON에서 쿼리 문자열 도구는 무엇을 하나요?

코드에서 JSON 설정을 만들었습니다 — 필터 파라미터, 분석 페이로드, OAuth state — 이제 그것을 URL 뒤에 붙여야 합니다. 이 페이지가 그 지루한 마지막 단계를 처리합니다. 왼쪽에 JSON을 붙여 넣으면 오른쪽에 ?customer=Ava+Chen&status=active&total%5Bgte%5D=49.99&page=2&tag=premium&tag=verified가 돌아오고, 링크나 fetch 호출, 웹훅 URL에 바로 떨어뜨릴 수 있습니다. 배열은 반복 키로 펼쳐지고(요즘 서버라면 모두 이해하는 관행입니다), 값은 올바르게 퍼센트 인코딩되며, 선두 ?도 포함되어 URL에 그대로 붙여 넣을 수 있습니다.

변환에는 브라우저 내장 URLSearchParams를 사용합니다 — 서버 프레임워크가 돌아온 요청을 파싱할 때 쓰는 것과 같은 기본 도구입니다. URLSearchParams는 WHATWG URL Standard에 따라 application/x-www-form-urlencoded 출력을 만들고, JSON은 RFC 8259에 따라 JSON.parse로 파싱됩니다. 숫자와 불리언은 문자열로 변환되고(쿼리 문자열에는 타입 시스템이 없습니다), null과 undefined 값은 건너뛰며, 중첩 객체는 친절한 오류를 띄워서 평탄화할 수 있게 해 줍니다.

모든 작업은 브라우저에서 로컬로 실행됩니다 — 업로드 없음, 서버 왕복 없음, 로깅 없음. 반대 문제가 있다면(쿼리 문자열을 JSON으로 바꾸고 싶다면) 쿼리 문자열에서 JSON으로를 사용하세요. URL 전체를 프로토콜, 호스트, 경로, 검색 부분으로 분해하고 싶다면 URL에서 JSON으로 페이지나 URL 파서가 더 적합합니다. 여기서 쓰이는 퍼센트 인코딩 규칙은 RFC 3986 §2.1에 정의되어 있고, 더 넓은 URL 파싱 모델은 MDN URL API 레퍼런스에 있습니다.

JSON을 쿼리 문자열로 변환하는 방법

세 단계입니다. 각 단계는 페이지의 버튼 하나에 대응됩니다.

JSON 객체 붙여 넣기

왼쪽 패널에 JSON을 넣습니다. 최상위 값은 객체여야 합니다 — 배열과 원시값은 쿼리 파라미터에 깔끔하게 매핑되지 않습니다. 샘플을 누르면 문자열, 숫자, 대괄호 키, 배열을 포함한 현실적인 이커머스 필터 페이로드가 들어옵니다. 샘플:

{
  "customer": "Ava Chen",
  "status": "active",
  "total[gte]": "49.99",
  "page": 2,
  "tag": ["premium", "verified"]
}

숫자와 불리언은 문자열로 변환됩니다(쿼리 문자열에는 타입이 없습니다). <code>null</code>과 <code>undefined</code> 값은 건너뜁니다 — 그렇지 않으면 URL이 지저분해지기만 합니다.

쿼리 문자열 읽기

오른쪽 패널은 입력에 맞춰 갱신됩니다. 위 샘플은 ?customer=Ava+Chen&status=active&total%5Bgte%5D=49.99&page=2&tag=premium&tag=verified를 만들어 냅니다. 공백은 +가 되고(form-encoded 스타일 — FAQ 참조), 대괄호는 %5B/%5D가 되며, tag 배열은 두 개의 별도 tag= 파라미터로 펼쳐집니다.

복사 또는 다운로드

복사를 누르면 쿼리 문자열이 클립보드로 가고, 다운로드를 누르면 querystring.txt로 저장됩니다. 지우기는 입력 패널을 초기화합니다.

실제로 쓰이는 상황

공유 가능한 필터 URL 만들기

대시보드에서 사용자가 고객, 상태, 날짜 범위로 주문을 필터링한다고 합시다. 상태는 컴포넌트 안에 JSON 객체로 살고 있습니다({customer: "Marco Rivera", status: "active", date_from: "2026-04-01"}). 뷰를 공유 가능하게 하려면 그것을 URL에 덧붙이면 됩니다 — 여기에 JSON을 붙이고, 쿼리 문자열을 복사하면 끝. 이커머스 카테고리 페이지, 검색 결과, 상태가 있는 어떤 필터에도 똑같이 통합니다.

웹훅 콜백 URL 구성하기

Stripe, GitHub, 그리고 대부분의 웹훅 발신자는 콜백 URL의 쿼리 문자열에 메타데이터를 넣게 해 줍니다. 사용자를 설명하는 JSON 객체({userId: "USR-1001", source: "checkout", flow: "onboarding"})가 있고, 그것을 https://api.example.com/webhook?...에 붙여야 합니다. 붙여 넣고, 복사하고, 붙여 넣고 — 각 값을 직접 URL 인코딩하면서 어떤 글자를 이스케이프해야 할지 고민하는 것보다 훨씬 낫습니다.

OAuth와 OpenID URL 생성

OAuth 인증 URL은 보통 8~12개의 쿼리 파라미터로 이루어집니다: client_id, redirect_uri, scope, state, response_type 등. JSON으로 먼저 만들어서(깨끗이 보기 위해) 여기서 변환하는 게, 문자열을 이어 붙이며 인코딩이 맞기를 기도하는 것보다 빠릅니다. state 파라미터에는 nonce와 복귀 경로가 들어가는 경우가 많아 그 자체로 또 이스케이프가 필요합니다.

HTTP 클라이언트에서 API 요청 만들기

cURL, Postman, 또는 빠르게 짠 fetch()로 API 엔드포인트를 시험할 때, 보통 파라미터는 문서에서 가져온 JSON 조각 형태로 가지고 있습니다. 여기서 변환해서 URL에 붙이고 요청을 날리세요. 주문 ORD-1001의 상품 필터 {"sku": "SKU-101", "include": "variants"}는 한 번의 붙여 넣기로 ?sku=SKU-101&include=variants가 됩니다.

자주 묻는 질문

왜 공백이 %20이 아니라 +로 인코딩되나요?

출력이 form-encoded(application/x-www-form-urlencoded) 형식이기 때문입니다. 모든 브라우저가 보내고, 모든 서버가 쿼리 문자열에서 기대하는 형식입니다. RFC 3986은 기술적으로는 URI 컴포넌트에서 %20을 선호하지만, 공백을 +로 쓰는 form-encoded 관행은 RFC 3986보다 오래되었고 90년대부터 쿼리 문자열에서 써 온 방식입니다. 최근 서버 프레임워크는 모두 둘 다 디코딩합니다 — Express, FastAPI, ASP.NET, Spring, Rails, Django 등. 굳이 %20이 필요하다면 출력에 .replace(/\+/g, "%20")를 한 번 돌려 주세요.

배열은 어떻게 인코딩되나요?

반복 키로 펼쳐집니다. {"tag": ["premium", "verified"]}는 tag=premium&tag=verified가 됩니다. URLSearchParams가 만드는 관행이고, 받는 쪽에서 URLSearchParams.getAll()을 쓰면 깔끔하게 왕복됩니다. 서버가 대괄호 표기(tag[]=premium&tag[]=verified — PHP와 Rails에서 흔합니다)를 기대한다면 JSON 키를 tag 대신 tag[]로 지으세요.

JSON에 중첩 객체를 둘 수 있나요?

아니요 — 쿼리 문자열은 설계상 평면입니다. 페이지는 중첩 객체를 발견하면 친절한 오류를 돌려주므로 평탄화할 수 있습니다. 가장 흔한 회피책은 대괄호 표기 키입니다: {"filter": {"status": "active"}} 대신 {"filter[status]": "active"}로 쓰면 됩니다. Rails, PHP, qs.js 같은 프레임워크는 서버 쪽에서 그것을 다시 중첩 객체로 파싱합니다. 진짜 모호함이 없다면 그냥 개념적으로 평탄화해서 {"status": "active"}로 끝내도 됩니다.

null과 undefined 값은 어떻게 되나요?

건너뜁니다. {"customer": "Ava Chen", "status": null}은 ?customer=Ava+Chen&status=가 아니라 ?customer=Ava+Chen이 됩니다. 이유: URL의 status=는 "빈 문자열"을 의미하고, 이는 "status 없음"과는 다른 실제 값입니다. null을 빈 값으로 보내면 정보가 손실되고 헷갈립니다. 정말 status=를 보내고 싶다면 {"status": ""}를 보내세요.

숫자와 불리언은 타입 그대로 보존되나요?

아니요 — 쿼리 문자열은 문자열만 운반합니다. {"page": 2}는 page=2가 되고, {"debug": true}는 debug=true가 됩니다. 서버 코드가 스키마를 알고 있어서 다시 타입으로 되돌려야 합니다. 이건 쿼리 문자열(과 폼 데이터)의 본질입니다 — 와이어 포맷은 숫자 2와 문자열 "2"를 구분하지 않습니다. 타입이 있는 파라미터가 필요하다면 요청 본문에 JSON으로 넣어 보내세요.

키나 값의 유니코드와 이모지는 어떻게 처리되나요?

깔끔하게 처리됩니다. URLSearchParams는 바이트를 UTF-8로 인코딩하고, 안전 집합 밖의 것은 퍼센트 이스케이프합니다. 그래서 {"name": "中文"}은 name=%E4%B8%AD%E6%96%87이 되고, {"reaction": "🔥"}는 reaction=%F0%9F%94%A5가 됩니다. 받는 쪽에서는 URLSearchParams(또는 어떤 프레임워크의 쿼리 파서든) 그대로 디코딩합니다. 만질 인코딩 설정 같은 건 없습니다 — UTF-8은 URL Standard가 정한 것이니까요.

선두의 물음표는 무엇을 위한 건가요?

출력을 URL에 바로 붙여 넣을 수 있게 하기 위해서입니다 — https://shop.example.com/orders + ?customer=Ava+Chen&page=2 = 동작하는 URL. 이미 쿼리 문자열이 있는 URL에 덧붙이려면 ?를 떼고 &를 쓰세요. 입력이 비어 있거나 {}라면 출력도 비어 있습니다(혼자 떨어진 ?는 나오지 않습니다).

다른 URL & JSON 도구

쿼리 문자열을 만드는 건 한 가지 작업일 뿐입니다. 같이 쓰면 좋은 도구들:

JSON에서 쿼리 문자열로