[Web] URL Encoding

✅ 1. URL 인코딩이란?

URL 인코딩(URL Encoding, Percent-Encoding)은 URL에 포함되면 안 되는 특수문자, 공백, 한글 등 비ASCII 문자를 안전한 ASCII 문자로 변환하는 방식입니다.

예:

https://example.com/search?query=자바 프로그래밍
↓ 인코딩 ↓
https://example.com/search?query=%EC%9E%90%EB%B0%94%20%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D

---

✅ 2. 왜 인코딩이 필요한가?

✔️ 이유 1: URL은 ASCII 문자만 허용됨

• URL은 RFC 3986에 따라 ASCII 문자로만 구성되어야 함
• 공백, 한글, %, #, &, = 등의 문자는 ASCII가 아니거나 URL에서 특별한 의미를 가지므로 인코딩이 필수

✔️ 이유 2: 의미 중복 방지

예: &는 파라미터 구분자로 사용되는데,

• 값에 &가 있으면 제대로 파싱되지 않음
• 그래서 값 안의 &는 %26으로 변환되어야 함

---

✅ 3. 어떤 문자들이 인코딩되어야 하나?

✅ 인코딩 대상 문자는 크게 3가지 범주

분류	문자 예	설명
예약 문자	: / ? # [ ] @, ! $ & ' ( ) * + , ; =	URL의 구조에 사용되므로 반드시 인코딩 필요
공백 문자	(스페이스)	%20 또는 +
비ASCII 문자	한글, 일본어, 이모지 등	UTF-8로 인코딩 후 퍼센트 인코딩

📌 특수한 규칙

• 스페이스(공백)
  • 쿼리 문자열에서는 보통 +
  • URL 경로나 JSON 값 등에서는 %20로 인코딩
  • 일부 서버는 두 방식 모두 인식, 하지만 엄밀히는 %20이 표준

---

✅ 4. 자주 사용되는 문자 인코딩 예시

문자	인코딩
공백	%20 또는 +
한글	%ED%95%9C%EA%B8%80
=	%3D
&	%26
/	%2F
?	%3F
"	%22
:	%3A

---

✅ 5. 실무에서 언제 인코딩을 신경 써야 할까?

🔹 클라이언트(Open API 호출 시)

• 쿼리스트링에 한글, 특수문자 포함 시
  • 직접 호출하는 curl, axios, fetch, HttpClient, RestTemplate 등에서 파라미터를 encodeURIComponent 등으로 인코딩

const encoded = encodeURIComponent("한글 검색어");
fetch(`https://api.example.com/search?query=${encoded}`);

🔹 서버(API 제공 시)

• 쿼리스트링 파라미터 자동 디코딩:
  • 대부분의 웹 프레임워크는 자동 디코딩해줌 (Spring, Express, Flask 등)
  • 하지만 경로(/path/{variable})에 포함된 값은 수동 처리 필요할 수 있음

🔹 경로(URL path parameter)도 인코딩 필요

예:

GET /user/홍길동
↓ 인코딩 ↓
GET /user/%ED%99%8D%EA%B8%B8%EB%8F%99

⚠️ API 경로 변수(Path Variable)에 특수문자가 들어갈 경우 반드시 인코딩해야 함

---

✅ 6. 각 언어별 인코딩 방법

언어	인코딩 함수	설명
JavaScript	encodeURIComponent()	주로 사용, 쿼리 파라미터용
Java	URLEncoder.encode(str, "UTF-8")	Java에서 GET 요청 시
Python	urllib.parse.quote()
Node.js	encodeURIComponent()
PHP	urlencode()
Curl	--data-urlencode	GET/POST 요청 시

---

✅ 7. 자주 발생하는 실수와 예방법

실수	문제 상황	해결 방법
한글/공백 안 인코딩	서버에서 400 오류	encodeURIComponent() 사용
인코딩을 두 번 함	%25EC%9E%90%EB%B0%94 → 깨짐	한 번만 인코딩해야 함
Path 파라미터 미인코딩	API 경로 인식 오류	pathVariable도 인코딩 필요
쿼리 인코딩 시 +를 %20로 바꿔야 하는 경우	일부 서버는 +를 공백이 아닌 문자로 인식	%20로 강제 인코딩하거나 서버 설정 확인

---

✅ 정리 요약

항목	설명
목적	URL에 안전하게 데이터를 포함시키기 위해
대상	특수문자, 한글, 공백 등
클라이언트	요청 전 인코딩 필요 (encodeURIComponent)
서버	대부분 자동 디코딩, 경로 변수는 주의
위치	Query string, Path variable 모두

---

📌 실무 팁

• 모든 API 요청에 대한 파라미터는 미리 인코딩 유틸을 만들어 처리
• API 문서에 "URL 인코딩 필수" 문구를 명시
• 특히 파라미터가 사용자 입력(한글, 특수문자 포함)이라면 항상 인코딩 확인

---

✅ 참고: 스프링에서 인코딩 책임은 누구에게?

|구분 인코딩 주체 설명
|----|---|---|-----|
|@RequestParam ✅ 클라이언트 쿼리 파라미터(?keyword=자바)는 반드시 인코딩 필요.
|@PathVariable ✅ 클라이언트 경로에 포함된 한글/공백/특수문자 등은 인코딩 필요.
스프링 서버 ❌ 서버는 인코딩 안 해줌 서버는 URL 디코딩만 자동 처리함 (%EC%9E%90%EB%B0%94 → 자바)