포스트

datetime 버그 두 가지: offset 손실과 UTC/KST 날짜 비교

시간 관련 버그는 보통 타입 선택 실수로 보이지만, 실제로는 저장 형식, 파서, 타임존 기준이 흐린 계약에서 시작되는 경우가 많다. 운영에서만 드러난 datetime 버그를 통해 그 이유를 정리한 글이다.

상황

시간 관련 버그가 두 번 발생했다.

1. 운영에서만 DateTimeParseException 발생

  • 외부 API는 2026-02-05T12:00:00+00:00 같은 offset 포함 문자열을 내려준다
  • 중간 저장 계층이 이 값을 LocalDateTime으로 바꾸면서 offset을 버린다
  • 도메인으로 되돌린 값은 2026-02-05T12:00:00처럼 offset이 없다
  • 마지막 소비자는 OffsetDateTime.parse(...)로 읽다가 운영에서 예외가 난다

2. 새벽 시간대에 “오늘” 데이터가 “내일”로 밀리거나 반대로 분류됨

  • DB에는 UTC 기준 시간이 저장돼 있다
  • 조회 코드가 KST로 변환하지 않고 바로 toLocalDate()로 비교한다
  • UTC 15:00 이후 데이터는 사용자 기준으로 이미 다음 날인데, 시스템은 같은 날로 분류한다

두 버그의 원인은 같았다. 값의 시간 형식, timezone 의미, 다음 단계가 기대하는 파서가 계약으로 고정돼 있지 않았다. 타입을 잘못 고른 문제(String 대신 Instant, LocalDateTime 대신 OffsetDateTime)처럼 보이지만, 저장 형식과 파서와 timezone 기준이 서로 다른데 하나의 계약처럼 취급한 것이 원인이다.

“ISO 8601”만으로는 계약이 아니다

시간 필드에 흔히 이런 주석을 단다.

1
val datetime: String // UTC, ISO 8601 형식

ISO 8601에는 여러 형식이 있다.

  • 2026-02-05T12:00:00
  • 2026-02-05T12:00:00+00:00
  • 2026-02-05T12:00:00Z

파서도 다르다. offset이 없는 형식은 LocalDateTime.parse, offset이 있는 형식은 OffsetDateTime.parse로 읽는다. 그래서 시스템의 각 지점이 이 값을 다르게 해석할 수 있다.

  • Provider는 offset 포함 문자열을 만든다
  • Entity는 LocalDateTime으로 파싱하며 offset을 버린다
  • DB에는 offset 없는 값이 저장된다
  • Consumer는 다시 OffsetDateTime.parse로 읽는다

각 코드는 문제가 없어 보이지만 전체 라운드트립 계약은 깨져 있다.

운영에서만 발생한 이유

1
2
3
4
5
6
7
8
9
Provider
  → "2026-02-05T12:00:00+00:00"  (offset 포함)
Entity
  → LocalDateTime 으로 파싱       (offset 손실)
DB 저장
Entity.toDomain()
  → "2026-02-05T12:00:00"        (offset 없음)
Consumer
  → OffsetDateTime.parse(...)    (예외)

단계별로 보면 이상한 곳이 없다.

  • Provider는 정상 문자열을 만들었다
  • Entity는 값을 저장했다
  • DB도 값을 가지고 있었다
  • Consumer도 자기가 기대하는 타입의 파서를 썼다

단위 테스트는 보통 도메인 객체를 픽스처로 직접 만들기 때문에 Provider → Entity → DB → Entity → Consumer 라운드트립을 재현하지 않는다. 그래서 단위 테스트는 통과하고, 파일 단위 코드 리뷰도 통과하고, 운영에서 특정 데이터가 들어왔을 때만 깨진다.

UTC/KST 비교 기준

UTC 기준으로 2026-04-01T15:00:00이 저장돼 있으면:

  • UTC로는 4월 1일 15시
  • KST로는 4월 2일 0시

변환 없이 날짜만 뽑아 비교하면 4월 1일로 분류된다. 사용자 기준으로는 이미 다음 날이다.

다음 코드가 이 문제를 만든다.

1
item.dateTime().toLocalDate().isEqual(curdate)
1
data.dateTime().isBefore(LocalDateTime.now())

이 코드에는 답하지 않은 질문이 있다.

  • 저장값은 UTC인가
  • 비교 기준은 UTC인가 KST인가
  • “오늘/내일”은 사용자 기준인가 저장 기준인가

답하지 않은 채 날짜만 비교하면 9시간 경계에 걸린 데이터가 잘못 분류된다. 변환을 명시하면 다음과 같다.

1
2
3
4
5
item.dateTime()
    .atZone(ZoneOffset.UTC)
    .withZoneSameInstant(kst)
    .toLocalDate()
    .isEqual(curdate)

코드가 길어진 것은 숨어 있던 계약을 드러냈기 때문이다.

타입보다 먼저 고정할 것

시간 타입에 대한 일반적인 권장은 Instant를 쓰고, offset이 있으면 OffsetDateTime을 쓰고, LocalDateTime은 피하라는 것이다. 다만 외부 API 계약, DB 제약, 라이브러리 호환성 때문에 String을 유지해야 할 때가 있다. DynamoDB는 attribute converter나 기존 스키마 때문에 타입을 바로 바꾸기 어려울 수 있다.

이 경우 다음 네 가지를 고정한다.

  1. 저장 문자열 형식
  2. offset 정보 유무
  3. offset이 없다면 의미상 timezone
  4. 소비자가 써야 할 파서

주석은 이렇게 쓴다.

1
2
val datetime: String
// ISO_LOCAL_DATE_TIME (offset 없음, 의미상 UTC)
1
2
val datetime: String
// ISO_OFFSET_DATE_TIME (offset 포함, 항상 +00:00)

이렇게 적어야 Provider, Entity, Consumer가 같은 계약을 본다.

테스트: 라운드트립과 경계 시각

단일 파서 테스트로는 부족하다. 라운드트립 전체를 테스트한다.

  1. Provider가 만든 문자열을 넣는다
  2. Entity로 변환한다
  3. DB 저장/복원을 거친다
  4. 도메인으로 되돌린다
  5. Consumer가 기대하는 파서로 읽는다

검증할 것은 “이 함수가 파싱되는가”가 아니라 “이 값이 시스템을 한 바퀴 돌아도 같은 의미를 유지하는가”다.

UTC/KST 비교는 경계 시각을 fixture로 넣고 KST 기준 오늘/내일 분류를 확인한다.

  • 14:59 UTC
  • 15:00 UTC
  • 23:59 UTC
  • 00:00 UTC

시간 코드 리뷰 체크리스트

  • 이 값은 문자열인가, 객체인가
  • 문자열이라면 정확히 어떤 포맷인가
  • offset이 있는가 없는가
  • offset이 없다면 의미상 어떤 timezone인가
  • 저장 기준과 조회 기준이 같은가
  • 날짜 비교 전에 사용자 기준 timezone으로 변환했는가
  • 소비자 파서가 생산자 형식과 일치하는가

계약이 분명하면 임시로 String을 유지해도 문제 범위를 줄일 수 있다.

정리

  • ISO 8601 같은 넓은 표현으로 계약을 적지 않는다
  • offset 포함 여부와 의미상 timezone을 같이 적는다
  • 문자열을 유지하더라도 producer와 consumer의 파서를 같이 고정한다
  • 시간 테스트는 단일 함수보다 라운드트립과 경계 시각 중심으로 짠다
  • 날짜 비교는 toLocalDate() 전에 어떤 timezone 기준인지 먼저 드러낸다
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.