파이썬 JSON 직렬화 ensure_ascii=False로 한글 깨짐 완벽 방지하기

🔍 JSON 직렬화와 한글 깨짐 문제 이해하기

파이썬에서 JSON은 데이터를 교환하거나 저장하는 과정에서 가장 많이 쓰이는 형식 중 하나입니다.
특히 웹 서비스의 API 통신이나 로그 관리, 설정 파일 등에서 널리 활용됩니다.
하지만 기본적으로 json.dumps()를 사용할 경우, 한글이 유니코드 이스케이프 형태인 \uXXXX 방식으로 변환되어 출력되는 문제가 생깁니다.
예를 들어 “안녕하세요”라는 문자열은 “\uc548\ub155\ud558\uc138\uc694″처럼 표현되는데, 이는 프로그램 상에서는 문제없이 처리되지만 사람이 읽을 때는 불편하고 직관성이 떨어집니다.

이 현상이 발생하는 이유는 JSON 표준이 본래 ASCII 문자 기반으로 설계되었기 때문입니다.
영문이나 숫자는 그대로 표현되지만, 비ASCII 문자(한글, 일본어, 이모지 등)는 안전하게 전송하기 위해 유니코드 이스케이프 처리되는 것이죠.
따라서 한글 데이터를 다루는 한국 개발자에게는 이 과정이 매번 불편하게 다가올 수밖에 없습니다.

📌 실제 한글 깨짐 현상 예시

import json

data = {"message": "안녕하세요"}
result = json.dumps(data)
print(result)
# 출력: {"message": "\uc548\ub155\ud558\uc138\uc694"}

위 코드처럼 기본 설정으로 직렬화하면 한글이 모두 \uXXXX 형태로 변환됩니다.
이는 시스템 내부적으로는 안전한 방식이지만, 로그 파일이나 API 응답 결과를 직접 확인할 때는 불편함이 큽니다.
따라서 이 문제를 해결하기 위해 ensure_ascii=False 옵션을 활용해야 합니다.

⚙️ ensure_ascii 옵션의 동작 원리

한글 깨짐 문제를 해결하는 핵심은 json.dumps() 함수의 ensure_ascii 옵션에 있습니다.
이 옵션은 직렬화 과정에서 비ASCII 문자를 어떻게 처리할지 결정하는 역할을 합니다.
기본값은 True이므로 모든 비ASCII 문자가 \uXXXX 형태로 변환되지만, 이를 False로 지정하면 한글이 원래 문자 그대로 출력됩니다.

🔎 옵션별 비교

표를 보면 알 수 있듯이, 단순히 옵션을 False로 설정하는 것만으로도 한글을 사람이 읽기 좋은 상태로 유지할 수 있습니다.
따라서 로그, API 응답, 설정 파일 등에서 한국어 데이터를 직관적으로 다루려면 반드시 적용해야 하는 설정입니다.

⚠️ 놓치기 쉬운 부분

📝 코드 예제로 살펴보는 직렬화 결과

이제 실제 코드를 통해 ensure_ascii 옵션의 차이를 확인해 보겠습니다.
아래 예제는 동일한 데이터를 직렬화하면서 옵션 값에 따라 결과가 어떻게 달라지는지 비교할 수 있습니다.

import json

data = {"city": "서울", "greeting": "안녕하세요"}

# 기본값 (ensure_ascii=True)
result1 = json.dumps(data)
print(result1)
# 출력: {"city": "\uc11c\uc6b8", "greeting": "\uc548\ub155\ud558\uc138\uc694"}

# ensure_ascii=False 설정
result2 = json.dumps(data, ensure_ascii=False)
print(result2)
# 출력: {"city": "서울", "greeting": "안녕하세요"}

코드 실행 결과를 보면 ensure_ascii=False를 적용했을 때 한글이 원래의 모습 그대로 직렬화된다는 것을 확인할 수 있습니다.
이 차이 하나로 출력된 데이터의 가독성이 크게 달라지며, 특히 로그 분석이나 디버깅 과정에서 시간을 절약할 수 있습니다.

💡 추가 예제: 들여쓰기 옵션과 함께 사용하기

가독성을 높이기 위해 indent 옵션과 함께 사용하는 경우도 많습니다.
이렇게 하면 JSON 데이터를 사람이 읽기 좋은 형태로 정리할 수 있습니다.

result3 = json.dumps(data, ensure_ascii=False, indent=4)
print(result3)

# 출력:
# {
#     "city": "서울",
#     "greeting": "안녕하세요"
# }

💾 파일 저장 시 인코딩 처리 방법

JSON 직렬화된 데이터를 파일로 저장할 때는 단순히 ensure_ascii=False만으로는 충분하지 않습니다.
파일 시스템에 기록되는 과정에서 인코딩 문제가 발생하면 한글이 깨질 수 있기 때문입니다.
따라서 파일을 열 때 반드시 UTF-8 인코딩을 지정해야 한글이 안정적으로 보존됩니다.

import json

data = {"title": "파이썬 JSON", "content": "한글 저장 테스트"}

# UTF-8 인코딩으로 파일 저장
with open("data.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=4)

위 예제에서 encoding=”utf-8″ 옵션을 지정했기 때문에 저장된 파일을 열면 한글이 원래 형태 그대로 유지됩니다.
만약 인코딩을 지정하지 않고 저장한다면 운영체제 기본 인코딩(예: Windows의 cp949)에 따라 한글이 깨질 수 있습니다.

📌 파일 읽기 시에도 주의해야 할 점

JSON 파일을 읽을 때도 동일하게 인코딩을 맞춰 주어야 합니다.
파일 저장 시 UTF-8을 사용했다면, 읽을 때도 반드시 encoding=”utf-8″ 옵션을 지정하는 것이 안전합니다.

# UTF-8 인코딩으로 파일 읽기
with open("data.json", "r", encoding="utf-8") as f:
    loaded = json.load(f)
    print(loaded)

✅ 실무에서 자주 하는 실수와 주의사항

파이썬에서 ensure_ascii=False 옵션을 활용하면 한글 깨짐 문제를 쉽게 해결할 수 있지만, 실무에서는 몇 가지 흔한 실수로 인해 여전히 문제가 발생하는 경우가 많습니다.
이 부분을 미리 알고 대비하면 디버깅 시간을 크게 줄일 수 있습니다.

⚠️ 실수 1: 파일 저장 시 인코딩 미지정

많은 개발자가 직렬화 과정에서는 ensure_ascii=False를 적용하면서도, 파일 저장 시 encoding=”utf-8″을 지정하지 않아 문제가 발생합니다.
특히 Windows 환경에서는 기본 인코딩(cp949)이 적용되어 한글이 깨지는 경우가 흔합니다.

⚠️ 실수 2: API 응답에서 Content-Type 누락

웹 서버에서 JSON 응답을 반환할 때 Content-Type: application/json; charset=utf-8 헤더를 누락하면, 클라이언트 환경에 따라 한글이 깨져 보일 수 있습니다.
따라서 서버 사이드에서 올바른 헤더를 반드시 명시해 주어야 합니다.

⚠️ 실수 3: 터미널 환경 차이 간과

직렬화된 JSON을 바로 터미널에 출력하는 경우, 사용하는 환경에 따라 한글이 깨져 보일 수 있습니다.
예를 들어 리눅스 터미널은 기본적으로 UTF-8을 지원하지만, 일부 Windows 콘솔은 그렇지 않습니다.
따라서 출력 확인 시 환경 설정까지 점검하는 습관이 필요합니다.

• 🛠️파일 저장 시 반드시 encoding=”utf-8″을 지정하기
• ⚙️API 서버에서 charset=utf-8 헤더 포함하기
• 🔌터미널 및 운영체제 기본 인코딩 환경 확인하기

❓ 자주 묻는 질문 (FAQ)