똑같은 이름인데 결과가 다르다고? Django 개발에서 urlencode를 사용하기 [ r1 ]

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

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

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

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

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

1. 핵심 차이점 한눈에 보기

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

2. 왜 Django 버전을 따로 쓸까? (가장 중요한 이유)

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

첫째, 리스트(Multi-value) 처리의 '안전장치'

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

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

둘째, QueryDict와의 완벽한 호환성

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

3. QueryDict를 활용한 실전 인코딩 사례

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

사례 1: 검색 필터 유지하며 페이지네이션 구현하기

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

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: 체크박스 다중 선택 데이터 전송

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

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. 마치며: 무엇을 선택해야 할까?

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

1. Django 프로젝트 내부에서 request.GET을 다루거나 웹 URL을 생성한다면?

   • 고민할 것 없이 django.utils.http.urlencode를 사용하세요.

2. Django와 무관한 독립적인 파이썬 스크립트를 작성한다면?

   • urllib.parse.urlencode를 사용하되, 리스트 데이터가 있다면 doseq=True를 잊지 마세요.

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