최신 REST, GET 기반 GraphQL 및 웹훅 엔드포인트는 다중 값 배열, 중첩 필터 객체, Base64 커서, URL 인코딩된 검색 구문을 단일 쿼리 스트링이나 application/x-www-form-urlencoded 요청 본문에 담아 전송하는 경우가 많습니다. 이러한 페이로드를 평면적인 원시 문자열 상태로 검사하거나 편집하면 %26 이스케이프가 깨지거나 대괄호 짝이 맞지 않는 오류가 발생하기 쉽습니다.
예를 들어 +로 인코딩된 공백, 중복 키, 중첩 대괄호 필터, 퍼센트 인코딩된 = 패딩이 포함된 Base64 페이지네이션 커서, 그리고 값 없는 플래그 파라미터가 결합된 API 검색 쿼리를 살펴보겠습니다.
?q=distributed+tracing&tag=otel&tag=grpc&filter[status]=open&filter[priority]=high&cursor=eyJpZCI6NDIwfQ%3D%3D&dry_run
이 문자열을 파싱하면 가독성이 뛰어나고 명확하게 구조화된 JSON 표현이 즉시 생성됩니다.
{
"q": "distributed tracing",
"tag": [
"otel",
"grpc"
],
"filter": {
"status": "open",
"priority": "high"
},
"cursor": "eyJpZCI6NDIwfQ==",
"dry_run": ""
}
구분자 분할이 퍼센트 디코딩보다 먼저 이루어져야 하는 이유
cursor=eyJpZCI6NDIwfQ%3D%3D가 "eyJpZCI6NDIwfQ=="로 깔끔하게 디코딩된 점에 주목하세요. 파서는 원시 문자열을 먼저 &로 분할하고, 각 쌍을 첫 번째 리터럴 =로 분할한 다음에야 비로소 +와 %XX 시퀀스를 디코딩합니다. 만약 단순한 스크립트가 &와 =로 분할하기 전에 전체 쿼리 스트링에 대해 decodeURIComponent()를 실행한다면, 이스케이프된 앰퍼샌드를 포함한 파라미터 값(R%26D -> R&D)이 두 개의 잘못된 파라미터로 쪼개지게 됩니다.
JSON 뷰와 키-값 테이블은 양방향으로 동기화되므로, 애플리케이션 코드에서 JSON 필터 객체를 붙여넣어 HTTP 요청에 바로 사용할 수 있는 올바르게 이스케이프된 쿼리 스트링을 즉시 직렬화할 수도 있습니다.