한글 쿼리 파라미터가 깨질 때, URL 인코딩을 두 번 하지 않는 법

검색어, 파일 이름, 사용자 입력처럼 한글이나 공백이 들어간 값을 URL 쿼리 파라미터에 넣으면 주소가 길고 낯선 문자 조합으로 바뀝니다. 이는 오류가 아니라 URL 인코딩의 결과일 수 있습니다. 문제는 이미 인코딩된 값을 한 번 더 인코딩하거나, 반대로 인코딩이 필요한 값을 그대로 요청에 넣을 때 생깁니다.

인코딩과 디코딩은 반대 작업입니다

인코딩은 사람이 읽는 문자를 URL에서 안전하게 전달할 수 있는 형태로 바꾸는 작업입니다. 디코딩은 그 결과를 다시 읽는 문자로 바꾸는 작업입니다.

예를 들어 공백은 %20처럼 보일 수 있습니다. 그런데 %20의 %까지 다시 인코딩하면 %2520이 되어 원래 의미와 달라질 수 있습니다. URL이 예상보다 길어지고 %25가 반복된다면 이중 인코딩을 의심해 볼 만합니다.

확인 순서

1. 값이 사람에게 읽히는 문장인지, 이미 %가 섞인 인코딩 문자열인지 구분합니다.
2. 이미 인코딩된 값처럼 보이면 먼저 디코딩해 원래 문장을 확인합니다.
3. 요청 직전에 한 번만 인코딩하고, 같은 값에 다시 적용하지 않도록 코드 위치를 정합니다.
4. 서버가 기대하는 파라미터 이름과 인코딩 방식을 API 문서에서 대조합니다.

바로정리의 형식 변환 도구에서는 짧은 예시 값을 인코딩·디코딩으로 왕복해 볼 수 있습니다.

도구: https://barojungri-tools-yh.yonggoo0001.chatgpt.site/

파이썬에서는 라이브러리에 맡기는 편이 안전합니다

문자열을 직접 이어 붙여 URL을 만들기보다, HTTP 라이브러리의 params 기능을 쓰면 인코딩을 한 곳에서 처리하기 쉽습니다.

python
import requests

response = requests.get(
    "https://example.com/search",
    params={"q": "한글 검색어"},
)


이 방식에서도 서버가 요구하는 문자셋이나 특수 규칙은 문서로 확인해야 합니다. 단순한 URL 인코딩은 인증, 권한, 요청 성공 여부를 보장하지 않습니다.

정리

URL이 깨져 보일 때는 무작정 변환을 반복하지 말고, 현재 값이 원문인지 인코딩 결과인지부터 확인하세요. 한 번만 인코딩하고, 전후 값을 비교하는 습관이 이중 인코딩 문제를 줄여 줍니다.