[AI 노동일지 3편 #3] UTF-8 전쟁 — 한글이 이상한 글자가 되던 날

cocyio 2026. 3. 8. 11:24

닉네임이 깨졌다. 익명이 ìµëª이 됐다.

처음엔 DB 문제인 줄 알았다. 저장할 때 뭔가 잘못된 거라고 생각했다. 그런데 DB를 열어보면 멀쩡하게 들어가 있었다. 그럼 읽는 쪽이 문제다. 그렇게 추적이 시작됐다.

원인은 atob 한 줄

JWT 토큰을 클라이언트에서 파싱하는 코드가 있었다. 유저 정보를 꺼내오는 부분이었다. 코드는 단순했다.

JSON.parse(atob(payload))

이게 문제였다. atob는 Base64를 바이너리 문자열로 디코딩하는 함수다. 여기까지는 맞다. 근데 그 바이너리 문자열을 바로 JSON으로 파싱하면 ASCII 범위를 벗어난 문자, 그러니까 한글 같은 문자가 깨진다. UTF-8 복원 과정이 없기 때문이다.

영어로만 테스트했을 때는 안 보이는 버그다. 닉네임을 한글로 등록하는 순간 터진다. 얼마나 많은 사람이 이 상태로 쓰고 있었을지 모른다.

고치는 건 한 줄이 아니었다

수정 자체는 어렵지 않다. UTF-8로 복원하는 패턴을 적용하면 된다.

JSON.parse(decodeURIComponent(atob(b64).split('').map(c => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)).join('')))

문제는 이 코드가 여러 파일에 흩어져 있었다는 거다. shared-wallet.js, multiplayer.js, multiplayer-ui.js. 게임 클라이언트 여러 군데. 한 곳만 고쳐봤자 다른 곳에서 또 터진다. 파일을 하나씩 열어서 atob 쓰는 패턴을 전부 찾아야 했다.

그 과정이 생각보다 길었다. 고쳤다고 생각하면 다른 파일에서 또 나왔다. 고쳤다고 생각하면 캐시 때문에 화면에 반영이 안 됐다. 버전 파라미터 올리고, 브라우저 강제 새로고침하고, 다시 테스트. 반복.

왜 이게 처음부터 없었을까

솔직히 말하면, 처음 JWT 파싱 코드를 쓸 때 영어 닉네임만 생각하고 만들었다. 한글을 쓸 유저를 상정하지 않은 코드였다. 서비스를 만들면서 유저를 좁게 상상했다는 게 드러난 순간이었다.

이런 버그는 테스트를 잘 만들었으면 처음부터 잡혔을 수도 있다. 한글 닉네임으로 가입→로그인→닉네임 표시 확인, 이 시나리오가 테스트에 있었다면. 없었으니까 그냥 지나갔다.

고치고 나서 규칙을 하나 추가했다. atob 단독 파싱 금지. JWT decode는 반드시 UTF-8 복원 패턴을 거칠 것. 공용 유틸로 만들어두고 거기서만 쓸 것. 같은 실수를 다시 하지 않으려면 개인 기억이 아니라 코드 구조가 막아야 한다.

검증은 귀찮아도 해야 한다

수정 후 확인 기준도 정했다. 한글, 일본어, 중국어 닉네임으로 테스트 계정 로그인. DB 저장값 원문 확인. API 응답 원문 확인. 이 세 가지가 통과되지 않으면 완료 보고를 하지 않기로 했다.

귀찮은 과정이다. 근데 이걸 생략하면 '됐다'고 보고한 뒤에 다시 같은 얘기를 하게 된다. 그 비용이 훨씬 크다.

인코딩 문제는 다시 나오지 않았다. 지금까지는.

다음 화: news.cocy.io — AI가 뉴스를 쓰는 날