AJAX 통신 시 한글 깨짐

웹 개발을 하다 보면 서버 콘솔(System.out.println)에는 한글이 예쁘게 잘 찍히는데, 브라우저로 넘어온 데이터나 팝업창에서는 ???나 알 수 없는 외계어로 깨져서 나오는 경우가 있습니다.

오늘은 이 문제가 발생하는 원인과 확실한 해결 방법을 정리해 보겠습니다.

1. 현상 (Problem)

• 서버 로그: dcList = {FILE_REAL_NAME=만족도 배너.png...} (정상)
• 브라우저/AJAX 결과: {"FILE_REAL_NAME":"??? ??.png"} (깨짐)

2. 원인 (Cause)

서버에서 데이터를 보낼 때, 브라우저에게 "이 데이터는 UTF-8 형식의 한글을 포함하고 있어"라고 명시적으로 알려주지 않았기 때문입니다.

특히 자바의 HttpServletResponse에서 getWriter()를 호출하여 스트림을 여는 순간, 서버는 현재 설정된 기본 인코딩(보통 ISO-8859-1)으로 데이터를 보낼 준비를 끝냅니다. 그 이후에 setContentType을 설정하면 브라우저가 이를 무시하거나 이미 늦어버린 상태가 됩니다.

---

3. 해결 방법 (Solution)

가장 중요한 것은 순서와 명시적 선언입니다.

✅ 순수 서블릿/Controller (PrintWriter 사용 시)

res.getWriter()를 호출하기 전에 인코딩 설정을 마쳐야 합니다.

public void ajaxMethod(HttpServletRequest request, HttpServletResponse res) throws Exception {
    try {
        // 1. 응답 인코딩을 UTF-8로 설정 (최우선)
        res.setCharacterEncoding("UTF-8");

        // 2. 브라우저에게 JSON 형태이며 UTF-8임을 알림
        res.setContentType("application/json; charset=UTF-8");

        // 3. 설정을 마친 후 Writer 객체를 생성
        PrintWriter out = res.getWriter();

        // ... 비즈니스 로직 및 JSON 변환 ...

        out.print(json);
        out.flush();
        out.close();
    } catch (Exception e) {
        e.printStackTrace();
    }
}

✅ Spring 프레임워크 (@RequestMapping 사용 시)

Spring을 사용한다면 어노테이션 속성만으로 간단히 해결할 수 있습니다.

@RequestMapping(value = "/your-url.do", produces = "application/json; charset=utf8")
@ResponseBody
public String yourMethod() {
    // 로직 수행 후 객체 리턴 시 자동 인코딩 적용
}

---

4. 요약 및 주의사항

1. 순서가 생명: 반드시 res.getWriter() 호출 전에 설정을 끝내세요.
2. MIME 타입 명시: JSON 데이터를 보낼 때는 text/html 대신 application/json을 사용하는 것이 표준입니다.
3. JSP 상단 설정: JSP 페이지 자체에서도 아래 코드가 포함되어 있는지 확인하세요.

   <%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>

---

마치며
한글 깨짐 문제는 결국 서버와 브라우저 사이의 약속(Header) 문제입니다. 위 설정만 정확히 지켜준다면 더 이상 ???로 가득한 화면을 보지 않아도 될 것입니다!

---

도움이 되셨다면 공감과 댓글 부탁드립니다!

---

블로그 포스팅 형식이 마음에 드시나요? 추가로 넣고 싶은 내용이나 수정하고 싶은 부분이 있다면 말씀해 주세요! 구체적인 코드 설명이나 이미지가 더 필요하시면 도와드리겠습니다.