개발을 하다 보면 종종 '데자뷔' 같은 순간을 마주하곤 합니다. 분명 아는 함수인데, `import` 경로를 보니 내가 알던 그 녀석이 아닐 때죠. Django 개발자에게 `urlencode`가 바로 그런 존재입니다.

Django를 조금 다뤄보신 분들은 `urlencode`가 django.utils.http에 있다는 것을 알지만, 처음 접하시는 개발자는 파이썬 표준 라이브러리로 유명한 urllib.parse.urlencode 를 꺼내어 쓰시는 경우가 많을 겁니다. (저또한 그랬습니다.)

파이썬 표준 라이브러리에도 있고 Django 유틸리티에도 있는 이 함수, 과연 아무거나 골라 써도 괜찮은 걸까요? 결론부터 말씀드리면 **"아니오"** 입니다. 두 함수의 미묘하지만 결정적인 차이를 정리해 보았습니다.

![a dev is being confused about choosing a method](/media/whitedec/blog_img/9215d69669ef4f36b9be389a5594ba1f.webp)

---

# 똑같은 이름인데 결과가 다르다고? Django 개발에서 urlencode를 사용할 때 흔히 하는 실수

파이썬의 `urllib.parse.urlencode`와 Django의 `django.utils.http.urlencode`는 이름과 목적이 같아 보이지만, Django 버전은 웹 개발의 특수한 상황을 해결하기 위해 한 층 더 진화한 형태입니다.

## 1. 핵심 차이점 한눈에 보기 {#sec-e4fba724ad11}

두 함수의 주요 차이점을 표로 요약하면 다음과 같습니다.

|**구분**|**urllib.parse.urlencode**|**django.utils.http.urlencode**|
|---|---|---|
|**소속**|파이썬 표준 라이브러리|Django 내장 유틸리티|
|**구현 방식**|표준 라이브러리 독자 구현|내부에서 `urllib` 버전을 확장 호출|
|**기본 동작**|딕셔너리를 쿼리 스트링으로 변환|**`QueryDict` 및 멀티밸류 처리에 최적화**|
|**리스트 처리**|`doseq=True` 옵션이 필수|**별도 옵션 없이도 리스트를 안전하게 처리**|

---

## 2. 왜 Django 버전을 따로 쓸까? (가장 중요한 이유) {#sec-4eb8047c69f0}

Django가 표준 라이브러리를 그대로 쓰지 않고 굳이 자체적인 `urlencode`를 만든 데에는 명확한 이유가 있습니다. 바로 **웹 환경에서의 안정성**과 **편의성** 때문입니다.

### 첫째, 리스트(Multi-value) 처리의 '안전장치' {#sec-0927ec9ca7b1}

웹 프로토콜에서는 하나의 키에 여러 값이 담기는 경우가 흔합니다 (예: `?tag=python&tag=django`). 파이썬 표준 `urllib` 버전은 리스트를 인코딩할 때 `doseq=True` 옵션을 수동으로 챙겨야 합니다. 이를 깜빡하면 리스트 객체 자체가 문자열로 변환되어 `tag=['python', 'django']` 같은 엉뚱한 결과가 생성됩니다.

반면 Django 버전은 "웹에서는 리스트를 펼쳐서 보내는 것이 기본"이라는 전제하에 설계되어, 별도 옵션 없이도 리스트 데이터를 완벽하게 인코딩합니다.

### 둘째, `QueryDict`와의 완벽한 호환성 {#sec-fc334b880462}

Django의 `request.GET`은 일반 딕셔너리가 아닌 `QueryDict` 객체입니다. `QueryDict`는 동일한 키에 여러 값을 가질 수 있는 특수 객체인데, Django의 `urlencode`는 이 객체의 특성을 정확히 이해하고 내부 메서드를 활용해 데이터를 누락 없이 변환합니다.

---

## 3. QueryDict를 활용한 실전 인코딩 사례 {#sec-d12e4e553206}

실제 프로젝트에서 Django의 `urlencode`가 빛을 발하는 두 가지 시나리오를 살펴보겠습니다.

### 사례 1: 검색 필터 유지하며 페이지네이션 구현하기 {#sec-6144c74d2640}

사용자가 선택한 여러 검색 조건을 유지하면서 페이지 페이지만 이동해야 할 때, `request.GET`을 통째로 인코딩하는 것이 가장 깔끔합니다.


```Python
from django.utils.http import urlencode

# 사용자가 ?category=tech&category=life&q=django 를 검색한 상황
def get_next_page_url(request):
    params = request.GET.copy()  # QueryDict 복사
    params['page'] = 2           # 페이지 번호만 업데이트
    
    # Django의 urlencode는 QueryDict의 멀티밸류(category 2개)를 알아서 처리함
    return f"/search/?{urlencode(params)}"

# 결과: /search/?category=tech&category=life&q=django&page=2
```

### 사례 2: 체크박스 다중 선택 데이터 전송 {#sec-5e6185fe793c}

여러 개의 체크박스 데이터를 딕셔너리 형태로 인코딩하여 다른 API나 페이지로 전달해야 할 때 유용합니다.


```Python
from django.utils.http import urlencode

data = {
    'user_id': 123,
    'selected_tags': ['python', 'backend', 'tips']
}

# 표준 urllib과 달리 doseq=True를 쓰지 않아도 됨
query_string = urlencode(data)
print(query_string)

# 결과: user_id=123&selected_tags=python&selected_tags=backend&selected_tags=tips
```

---

## 4. 마치며: 무엇을 선택해야 할까? {#sec-eb673ad941be}

선택의 기준은 명확합니다.

1. **Django 프로젝트 내부**에서 `request.GET`을 다루거나 웹 URL을 생성한다면?
    
    - 고민할 것 없이 **`django.utils.http.urlencode`**를 사용하세요.
        
2. **Django와 무관한 독립적인 파이썬 스크립트**를 작성한다면?
    
    - **`urllib.parse.urlencode`**를 사용하되, 리스트 데이터가 있다면 `doseq=True`를 잊지 마세요.
        

결국 Django의 버전은 표준의 기능을 모두 포함하면서 개발자의 실수를 줄여주는 '친절한 래퍼(Wrapper)'입니다. 작은 차이가 디버깅 시간을 줄여준다는 사실, 잊지 마세요!