URL 인코딩/디코딩

텍스트를 퍼센트 인코딩하거나, 인코딩된 값을 다시 읽습니다. 구성 값(component) 과 전체 URL 모드가 있으며, 구성 값 모드에서는 공백을 %20 대신 +로 바꾸는 옵션을 쓸 수 있습니다. 잘못된 % 시퀀스나 깨진 UTF-8 바이트열은 읽기 쉬운 오류로 보고합니다.

검증된 예

A&B를 구성 값으로 인코딩하면 &가 %26이 되어 쿼리가 쪼개지지 않습니다. 전체 URL 모드에서 이미 완성된 주소의 구조를 유지한 채 비ASCII만 인코딩할 때 유용합니다.

실수 패턴

• 쿼리 값에 전체 URL 모드를 씀 → &가 남아 매개변수 증가
• 인코딩된 문자열을 한 번 더 인코딩 → %25 증가
• 경로의 +를 공백으로 디코드 → C++ 손상

원칙·RFC 배경은 한글 URL 인코딩 가이드에, 빠른 실험은 워크벤치 URL 모드에도 있습니다.

쿼리 문자열을 안전하게 만드는 순서

1. 키와 값을 각각 준비합니다. 예: q=한글 검색, sort=최신.
2. 구성 값 모드로 값만 인코딩합니다.
3. ?q= · &sort= 같은 구조 문자는 직접 조립합니다. 구조까지 구성 값 모드로 인코딩하면 ?가 %3F가 되어 주소가 깨집니다.
4. 완성된 주소를 열어 보고, 필요하면 디코드 모드로 값을 회수합니다.

URLSearchParams를 쓸 수 있는 코드에서는 이 도구로 기대한 인코딩 형태를 확인한 뒤 구현을 맞추면 됩니다. 공백을 +로 쓰는 서버와 %20만 받는 서버가 섞여 있으면 옵션을 바꿔 가며 맞춥니다.

디코딩 사고 사례

로그에 %ED%95%9C가 그대로 보이면 아직 디코딩 전입니다. 화면에 %ED%95%9C가 보이고 그 문자열이 %25ED...에서 온 것이면 이중 인코딩입니다. 이 도구는 한 패스만 디코딩하므로, %25ED%2595%259C를 두 번 돌리면 한글로 돌아갑니다. 한 번에 과도하게 풀지 않는 것이 안전합니다.

EUC-KR로 인코딩된 옛 링크는 UTF-8 디코드로 복구되지 않습니다. 출처 시스템의 인코딩을 먼저 확인하세요. 배경 지식은 한글 URL 가이드에 있습니다.

구성 값 모드로 만드는 검색 URL 전체 예

목표: https://modu.tools/search?q=한글 검색&ref=docs

1. 구성 값 모드에서 한글 검색 → %ED%95%9C%EA%B8%80%20%EA%B2%80%EC%83%89
2. 구성 값 모드에서 docs → docs (영문만이면 거의 그대로)
3. 직접 조립: https://modu.tools/search?q= + (1) + &ref= + (2)

전체 URL 모드에 https://modu.tools/search?q=한글 검색을 넣으면 ?와 =는 남고 한글·공백만 인코딩됩니다. 이미 구조가 잡힌 주소를 정리할 때 쓰세요. 값만 인코딩해야 하는 단계에서는 구성 값 모드가 맞습니다.

플러스와 공백을 혼동하지 않기

HTML 폼 관례는 쿼리에서 공백을 +로 쓰기도 합니다. 구성 값 모드의 공백→+ 옵션을 켜면 한글 검색이 %ED%95%9C%EA%B8%80+%EA%B2%80%EC%83%89가 됩니다. 경로 조각에 이 옵션을 적용하면 C++ 같은 값이 깨질 수 있으므로, 경로에는 %20/%2B만 쓰세요. 디코드할 때 +를 공백으로 읽을지도 서버 규약에 맞춰 선택합니다.

이 페이지는 한 가지 변환에 집중합니다. JSON·CSV와 이어서 다루려면 워크벤치의 URL 모드를 쓰세요. 배경 이론은 한글 URL 인코딩 가이드에 있습니다.

디코드 결과를 다시 인코드해 보기

디코드 → 인코드를 한 번 왕복했을 때 원문과 같은지 보면, 공백·플러스 옵션이 서버 규약과 맞는지 빠르게 알 수 있습니다. 왕복 후 %20과 +만 다르고 의미는 같다면 옵션 차이입니다. 한글이 깨지면 UTF-8이 아닌 소스일 수 있습니다.