URL 인코딩에서 자주 하는 실수

URL 인코딩은 간단해 보이지만 실수하면 파라미터가 깨지거나 중복 인코딩되는 문제가 생깁니다. 특히 검색어, 리다이렉트 URL, 한글 경로, 서명된 요청을 다룰 때 어디서 인코딩하고 어디서 디코딩하는지 정해져 있지 않으면 디버깅이 길어집니다.

1) 전체 URL 인코딩은 피하기

일반적으로는 쿼리 파라미터 값만 인코딩하는 것이 안전합니다.

예: 검색어만 인코딩

q=hello world

→ q=hello%20world

2) 이미 인코딩된 값을 다시 인코딩하지 않기

• %20이 %2520으로 변하는 문제가 발생합니다.
• 서버에서 디코딩을 한 번만 수행하는지 확인하세요.
• 프레임워크 자동 디코딩 여부를 먼저 확인하세요.

3) 공백 처리 방식

• +는 쿼리 스트링에서 공백으로 해석되기도 합니다.
• 일반적으로 %20이 더 안전합니다.

4) 실무 팁

• 인코딩/디코딩 위치를 명확히 정리하세요. (클라이언트 vs 서버)
• 중복 인코딩이 발생하지 않도록 테스트 케이스를 추가하세요.
• 외부 API 서명 로직은 인코딩 순서를 문서와 정확히 맞추세요.

5) 바로 써보기

URL Encode/Decode에서 입력 문자열을 인코딩/디코딩해 정상 여부를 확인하세요.

6) encodeURI vs encodeURIComponent

• encodeURI: 전체 URL에 사용 (쿼리 구분자는 인코딩하지 않음)
• encodeURIComponent: 파라미터 값에 사용

이 둘을 섞어 쓰는 것이 대표적인 실수입니다. 예를 들어 전체 URL 문자열에 encodeURIComponent를 적용하면 :, /, ?, =까지 모두 바뀌어 URL 구조 자체가 깨집니다. 반대로 파라미터 값에 encodeURI를 쓰면 &나 =가 남아서 의도하지 않은 분리가 발생할 수 있습니다.

7) 서버 디코딩 위치

• 프레임워크가 자동으로 디코딩하는 경우가 많습니다.
• 이미 디코딩된 값을 다시 디코딩하면 깨질 수 있습니다.

8) 자주 보는 사례

검색어에 C++, #, &, 한글이 들어갈 때 문제를 가장 쉽게 재현할 수 있습니다. +는 어떤 환경에서는 공백으로 처리되고, 어떤 환경에서는 그대로 남기도 합니다. 또 리다이렉트 URL을 파라미터로 다시 감싸는 이중 URL 구조에서는 한 단계 바깥과 안쪽의 인코딩 규칙이 달라 혼란이 커집니다.

9) 체크리스트

• 어디서 인코딩/디코딩하는지 명확한가?
• 중복 인코딩이 발생하지 않는가?
• 공백이 의도대로 처리되는가?
• 전체 URL과 파라미터 값을 서로 다른 함수로 처리했는가?

10) 추가 예시

• 검색어에 #가 포함되면 반드시 인코딩해야 합니다.
• 서버에서 +를 공백으로 처리하는지 확인하세요.
• 리다이렉트 URL을 파라미터로 넘길 때는 안쪽 URL을 별도로 인코딩해야 합니다.