URL에 한글 넣었더니 깨졌다? URL 인코더로 1초 만에 해결한 썰

API 호출에 한글 파라미터를 넣었더니 에러가 났다

웹 개발을 하다 보면 URL에 한글을 포함해야 하는 경우가 종종 있다. 검색 API에 한글 키워드를 넣어서 호출한다든지, 한글 파일명을 URL로 전달한다든지. 근데 URL은 기본적으로 ASCII 문자만 허용하기 때문에 한글을 그대로 넣으면 깨지거나 에러가 난다.

처음 이 문제를 마주쳤을 때 한참 헤맸다. "왜 영어 키워드는 되는데 한글은 안 되지?" 검색해보니 URL 인코딩이라는 걸 해야 한다고 하더라. "서울"이라는 글자를 "%EC%84%9C%EC%9A%B8"로 변환해서 URL에 넣어야 한다는 거다. URL 인코더/디코더를 찾아서 해결했는데, 이후로 이 도구를 정말 자주 쓰고 있다.

인코딩과 디코딩 둘 다 되니까 편하다

이 도구의 좋은 점은 인코딩(한글 → %XX)과 디코딩(%XX → 한글) 둘 다 지원한다는 거다. 인코딩이 필요할 때도 있지만, 디코딩이 필요할 때도 꽤 많다. 예를 들어 서버 로그를 보다가 URL에 "%ED%95%9C%EA%B5%AD"이 적혀 있으면 이게 뭔 말인지 바로 안 보인다.

이걸 디코더에 넣으면 "한국"이라고 나온다. 아~ 이 사용자가 "한국"이라고 검색한 거구나. 로그 분석할 때 인코딩된 한글을 일일이 눈으로 해석하는 건 불가능하다. 디코더가 없으면 로그 분석 자체가 어려워진다.

웹 크롤링할 때 필수 도구가 됐다

웹 크롤링이나 스크래핑을 할 때도 URL 인코딩 문제를 자주 만난다. 특정 사이트의 검색 결과 페이지를 크롤링하려면 검색어가 포함된 URL을 만들어야 하는데, 한글 검색어를 인코딩하지 않으면 요청이 실패한다.

Python의 urllib.parse.quote() 함수를 쓸 수도 있지만, 빠르게 확인하고 싶을 때는 URL 인코딩 변환 사이트가 훨씬 편하다. 코드를 작성하기 전에 예상 URL을 먼저 만들어보고, 브라우저에 직접 붙여넣어서 제대로 동작하는지 확인한 다음에 코드에 반영하면 시행착오를 줄일 수 있다.

특수문자도 인코딩 대상이라는 걸 알게 됐다

URL 인코딩이 한글에만 필요한 줄 알았는데, 특수문자도 인코딩해야 하는 경우가 많다. 공백은 %20 또는 +로, &는 %26으로, =는 %3D로 변환해야 한다. 왜냐하면 이런 문자들은 URL에서 특별한 의미를 가지기 때문이다.

예를 들어 파라미터 값에 &가 포함되어 있으면 URL 파서가 이걸 파라미터 구분자로 해석해버린다. "Tom & Jerry"라는 값을 전달하려면 "Tom+%26+Jerry"로 인코딩해야 정확히 전달된다. 이런 세부적인 부분까지 이 도구가 자동으로 처리해주니까 실수할 일이 없다.

카카오톡 공유 링크 만들 때도 유용하다

개발 업무가 아니더라도 URL 인코딩이 필요한 순간이 있다. 카카오톡이나 문자로 링크를 보낼 때 한글이 포함된 URL이 깨져서 보이는 경우가 있다. 특히 위키백과 한국어판 링크가 그렇다. URL에 한글이 들어가 있어서 복사하면 퍼센트 인코딩된 긴 문자열이 된다.

반대로 누군가가 보내준 인코딩된 긴 URL이 뭔 내용인지 궁금할 때 디코더에 넣어보면 원래 한글이 보인다. 일반 사용자에게도 은근히 쓸모 있는 도구다. 특히 블로그를 운영하면서 한글이 포함된 포스트 URL을 다룰 때 자주 쓰게 된다.

JavaScript의 encodeURIComponent()와 비교

개발자라면 JavaScript의 encodeURIComponent() 함수나 Python의 urllib.parse.quote()를 쓸 수 있다. 코드 안에서 자동으로 처리해야 할 때는 당연히 이런 함수를 쓰는 게 맞다. 하지만 디버깅 중에 "이 값을 인코딩하면 어떻게 되지?" 하고 빠르게 확인하고 싶을 때는 웹 도구가 더 빠르다.

특히 여러 인코딩 결과를 비교해봐야 할 때, 코드에서는 매번 console.log()를 찍어야 하지만 웹 도구에서는 값만 바꿔가면서 바로바로 결과를 볼 수 있다. 코드와 웹 도구를 상황에 맞게 병행하는 게 가장 효율적이다.

이중 인코딩 실수를 조심하자

URL 인코딩에서 흔히 하는 실수가 이중 인코딩이다. 이미 인코딩된 문자열을 한 번 더 인코딩하면 %25EC%2584%259C 같은 괴상한 문자열이 된다. %가 %25로 다시 인코딩되기 때문이다. 서버에서 디코딩해도 원래 한글이 안 나오고 %EC%84%9C 같은 문자열이 나온다.

이런 실수를 방지하려면 인코딩 전에 해당 문자열이 이미 인코딩되어 있는지 확인해야 한다. 이 도구로 디코딩을 먼저 해보면 원본 상태인지 이미 인코딩된 상태인지 바로 알 수 있다. 디버깅할 때 이 습관이 시간을 많이 아껴준다.

마무리 – 웹 개발자의 생존 도구 중 하나

URL 인코딩/디코딩은 웹 개발에서 피할 수 없는 작업이다. 한글, 특수문자, 공백 등을 URL에서 안전하게 다루려면 인코딩이 필수다. URL 인코더/디코더를 북마크에 넣어두면 API 개발, 로그 분석, 크롤링, 링크 공유 등 다양한 상황에서 즉시 활용할 수 있다. 단순하지만 이 도구 없이 웹 개발하는 건 상상하기 힘들다.