설계·개발

한국 서비스의 시간대 처리: KST/UTC 혼동으로 생기는 버그와 안전한 날짜 설계

UTC 저장·KST 표시 원칙부터 자정·요일·이중 변환 버그를 피하는 날짜 헬퍼와 테스트 전략까지 정리합니다.

4분 읽기조코헌트 운영팀
목차

1. 먼저 시간의 종류를 분리하라

시간대 버그는 대부분 ‘순간’과 ‘달력 날짜’를 같은 값처럼 다루면서 시작합니다. 사용자가 결제한 시각, 댓글이 작성된 시각처럼 전 세계에서 같은 순간을 가리켜야 하는 값은 타임스탬프입니다. 반면 생일, 영업일, 매주 월요일 같은 값은 달력 날짜 또는 지역 기준의 일정입니다.

순간(Instant)과 달력 날짜(Date)

2026-11-18T10:00:00Z는 하나의 순간입니다. 한국 사용자에게는 KST 기준 2026-11-18 19:00으로 보일 수 있지만, 저장된 순간 자체가 바뀐 것은 아닙니다. 반대로 ‘11월 18일 공개’는 사용자의 지역이나 서비스 정책에 따라 별도로 해석해야 합니다.

저장·계산·표시를 나누기

실무에서 가장 관리하기 쉬운 기본값은 다음과 같습니다.

  • DB의 생성·수정 시각은 UTC 기준으로 저장
  • 서버 간 비교와 정렬은 UTC 기준으로 처리
  • 사용자에게 보여줄 때만 KST로 변환
  • ‘오늘’, ‘이번 주’, ‘영업일’은 기준 시간대를 명시한 뒤 계산

조코헌트처럼 한국 사용자를 주로 대상으로 하는 서비스라도, 표시와 저장을 한 단계로 섞으면 나중에 해외 사용자나 배치 작업을 붙일 때 수정 범위가 커집니다.

2. 자정 경계에서 버그가 드러난다

낮에 테스트하면 멀쩡한 날짜 코드가 자정 전후에만 틀리는 경우가 많습니다. 특히 서버가 UTC로 동작할 때 한국의 자정은 UTC 자정과 다릅니다.

‘오늘’은 서버의 오늘이 아니다

‘오늘 가입한 사용자’를 찾는 쿼리는 서버의 날짜 문자열을 그대로 쓰지 말고, KST 기준 하루의 시작과 끝을 먼저 계산해야 합니다. 그 경계값을 UTC로 변환한 뒤 DB의 UTC 시각과 비교하는 방식이 안전합니다.

예를 들어 KST 기준 하루의 시작은 00:00:00, 끝은 다음 날 00:00:00 직전입니다. 종료 시각을 23:59:59로 고정하기보다, 다음 날 시작 시각보다 작은지 비교하면 밀리초 정밀도 차이도 줄일 수 있습니다. 예약 작업을 설계할 때도 같은 원칙이 필요하므로 백그라운드 작업과 cron: 예약 실행·주기 작업을 안정적으로 돌리는 4가지 방법과 함께 확인해보세요.

요일은 문자열에서 다시 만들지 않는다

UTC 시각을 먼저 요일로 바꾼 다음 KST로 표시하면 일요일과 월요일이 어긋날 수 있습니다. ‘한국 기준 요일’을 구해야 한다면 먼저 KST로 변환하고, 그 결과에서 요일을 계산하세요. 날짜 문자열만 보고 임의로 +9시간을 더하는 방식은 이미 변환된 값에 다시 적용될 위험이 있습니다.

3. 호스트 타임존에 기대지 않는 헬퍼 만들기

개발 환경, CI, 배포 서버의 타임존이 다를 수 있다는 전제로 날짜 헬퍼를 한곳에 모으세요. 컴포넌트나 API 라우트마다 new Date()와 문자열 조작을 흩뿌리면 같은 입력이 서로 다르게 해석됩니다.

입력 규칙을 먼저 고정하기

헬퍼는 입력을 명확히 받게 합니다. 저장용 함수는 UTC 타임스탬프만 받고, 표시용 함수는 ‘UTC 순간’과 ‘표시할 시간대’를 받습니다. 시간대 정보가 없는 날짜 문자열은 순간으로 오해하지 않도록 별도 타입이나 검증을 두는 편이 좋습니다.

formatInZone(utcInstant, "Asia/Seoul")
startOfDayInZone(date, "Asia/Seoul")

함수 이름에 Utc, Kst, InZone처럼 기준을 드러내면 호출부만 읽어도 변환 방향을 알 수 있습니다. 날짜 관련 컬럼을 추가하거나 타입을 바꿀 때는 DB 스키마 마이그레이션 안전하게 하기: 운영 중인 서비스에서 컬럼 추가·삭제 체크리스트처럼 기존 데이터의 의미까지 함께 점검해야 합니다.

출력 규칙도 분리하기

API 내부에서는 가능한 한 ISO 형식의 UTC 값을 유지하고, 화면용 문자열은 가장 바깥 계층에서 만드세요. 이렇게 하면 정렬·필터링은 날짜 객체나 타임스탬프로 처리하고, 지역화된 문자열은 프론트엔드 또는 표현 계층에만 남길 수 있습니다.

4. 이중 변환을 막는 테스트 전략

실패하기 쉬운 패턴

  • UTC 문자열을 로컬 시간으로 파싱한 뒤 다시 KST로 변환
  • 이미 KST인 값을 UTC라고 이름 붙여 저장
  • 서버의 TZ 설정이 맞을 것이라고 가정
  • YYYY-MM-DD만으로 특정 순간을 표현
  • 테스트 날짜를 정오에만 두고 자정 경계를 검증하지 않음

특히 ‘KST로 바꾼 문자열’을 다시 날짜 객체에 넣는 코드는 런타임 설정에 따라 다르게 동작할 수 있습니다. 변환은 한 번만 하고, 변환 전후의 의미를 변수명으로 남기세요.

최소 테스트 케이스

다음 입력을 고정해 테스트하면 많은 문제를 빠르게 발견할 수 있습니다.

  • KST 자정 직전과 직후
  • UTC 날짜와 KST 날짜가 서로 달라지는 시각
  • 월말·연말 경계
  • 월요일 0시와 일요일 밤
  • 개발 환경과 CI에서 같은 결과가 나오는지

에러가 사용자에게 드러난 뒤 원인을 찾기보다, 날짜 변환 실패를 로그에 남겨야 합니다. 운영 중 장애 신호를 먼저 확인하려면 에러 모니터링 셋업: Sentry vs GlitchTip 셀프호스트, 1인 운영에서 장애를 먼저 아는 법도 참고할 만합니다.

5. 출시 전 날짜 처리 체크리스트

  • 각 날짜 필드가 순간인지 달력 날짜인지 정의했는가?
  • DB 저장 기준이 UTC인지 문서화했는가?
  • 화면 표시 시간대가 명시되어 있는가?
  • ‘오늘’, ‘이번 주’, ‘마감일’의 기준 시간대를 정했는가?
  • 날짜 헬퍼가 한곳에 모여 있는가?
  • 자정·월말·연말·요일 경계 테스트가 있는가?
  • 서버와 CI의 로컬 타임존이 달라도 같은 결과가 나오는가?

시간대 처리는 처음부터 완벽한 국제화 시스템을 만드는 일이 아닙니다. 먼저 값의 의미를 분리하고, UTC 저장·명시적 변환·경계 테스트라는 세 가지 규칙을 코드에 고정하는 것부터 시작하면 됩니다.

이 글 공유하기